документация

[Pigzinzspace]

содержание документа - принципы по которым составляется документация

когда надо оставлять комментарии:

• если это важная часть кода от правильного понимания и использования которой зависит работа других частей
• если есть входные или выходные данные не очевидные из кода
• если алгоритм кажется сложным или не тривиальным, и для его понимания (джуну) нужно много времени
• если в коде есть критические граничные условия: количество треугольников, количество цветов, размер строки, массива, матрицы ...
• если вы используете сторонний код, нужны существующие комментарии к этому коду из источника, ссылка на документацию и сам изначальный код, документация в папке там же где лежит скрипт, если она недоступна онлайн. естественно если это чужой код у нас должно быть разрешение на использование.

оформление:

• вся документация составляется в коде в виде комментариев
• комментарий оформляется в начале модуля если имеет отношение к модулю, перед объявлением переменной если имеет отношение к переменной или перед объявлением функции
• укажите ишу к которому относится документация в первой строке
• скопируйте во вторую строку объявления переменной или функции к которой относится комментарий