Как сделать комментарии к программе более полезными?

Question

Хай, ребята,

Я видел людей, которые включали комментарии в свою программу ..

• Это для улучшения связи между программистами и читаемость кода путем явного указания программистов намерения и предположения?

• Должны ли комментарии быть в технических терминах, а не в терминах естественного языка?

• Как использовать комментарии максимально эффективно?

• Действительно ли полезно добавлять комментарии к программе?

Answer 1

Комментарии должны использоваться только для объяснения , почему код такой, какой он есть. Он никогда не должен объяснять , что делает код. То, что делает код, описывается кодом.

При этом в некоторых языках есть инструменты, которые ищут специальные символы в комментариях для генерации документации. Ява является одним из таких языков. Но это не столько комментарии к коду, сколько документация, в которой используется тот же синтаксис, что и для языковых комментариев.

Answer 2

Написание понятного кода - это всегда первый шаг к тому, чтобы сделать ваш код легким для понимания. Затем вы можете объяснить неясные части, посмотрев на код в комментариях.

Для себя комментарии объясняют, о чем я думал в то время. Таким образом, через шесть месяцев, когда я не помню, что я писал, я могу использовать комментарии, чтобы понять.

Некоторые классические варианты использования комментариев:

• Объяснение, почему код не был выполнен самым очевидным образом - например, взаимодействие с системами, которые используют странные или старые способы общения.
• Объяснение того, какой код может называть этот код - например, в большой и сложной системе. Вы можете добавить примеры, показывающие код, который может понадобиться для вызова этого.
• Документирование исключений из текущей практики кодирования - например, устаревший код, который не подвергался рефакторингу для использования в существующих системах.

Как правило, если вы обнаружите, что делаете что-то неочевидное, прокомментируйте это.

Альтернативный способ комментирования - начать с записи тела функции в виде комментариев. Затем разбейте комментарии на части и поместите код внизу. Когда это наконец сработает, очистите и исправьте комментарии.

Ciao!

Answer 3

Комментарии могут использоваться для автоматического документирования, связи между другими разработчиками, памяти, списков задач или основных объяснений функциональности. Обратите внимание, что комментарии должны быть дополнительными - если ваш код нуждается в комментариях, вам необходимо пересмотреть свой код.

Чтобы быть как можно более эффективным, разработайте шаблон для ваших комментариев. Опять же, это не только поможет вам прочитать и понять ваш код, но также может помочь парсеру создать документацию для вас из ваших комментариев, если они Вы в едином формате по всему коду.

Answer 4

лучше сделать программу с самоописанием, тогда не нужно много комментариев.

Answer 5

Я стараюсь комментировать каждую функцию, описывая на высоком уровне, но точным образом, что делает функция. Точность должна быть такой, чтобы не нужно было читать тело функции, чтобы понять, что делает функция, или заново реализовать ее и заставить ее прекрасно работать с любым кодом, который ее вызывает.

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

Время от времени может быть что-то неясное или странное в том, что делается в коде - я это документирую. Все, что не является очевидным или интуитивно правильным, или о чем вы потратили некоторое время на размышления, должно быть задокументировано.

Представьте, что у вас проблема с памятью, и вы забудете написать эту программу через месяц. Тогда представьте, что вам нужно вернуться и исправить это. Что бы вы хотели прокомментировать и как сделать эти комментарии наиболее полезными для вас?

Answer 6

Сначала попробуйте написать код, чтобы люди могли следить без комментариев.