Руководство для начинающих по написанию комментариев?

Есть ли полное руководство по написанию комментариев к коду, предназначенное для начинающих разработчиков?

В идеале это будет охватывать, когда комментарии (и не следует) использовать, и какие комментарии должны содержать.

Этот ответ :

Не комментируйте то, что вы делаете, но ПОЧЕМУ вы это делаете.

О ЧЕМ заботится чистый, читаемый и простой код с правильным выбором имен переменных для его поддержки. Комментарии показывают структуру более высокого уровня для кода, который не может (или трудно) отображаться самим кодом.

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

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

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

Так что не документируйте, ЧТО делает код. Самодокументированный код должен позаботиться об этом. Документ, ПОЧЕМУ вы это делаете. Почему WHY обычно связаны с бизнес-правилами или архитектурой, они не будут часто меняться и так быстро устаревают в WHAT. Чехлы для документов. Исключения документов. Решения по оформлению документов. И самое главное документируйте те проектные решения, которые вы рассматривали, но решили не реализовывать (и документируйте, ПОЧЕМУ вы решили не использовать их)

Вы должны прочитать книгу « Чистый кодекс» Роберта Мартина . Это хорошо объясняет, что если вам нужны комментарии, скорее всего, вы не пишете правильно. В идеале ваш код должен быть «комментируем». В книге «Чистый кодер» объясняется, как это сделать, так что комментарии не нужны, и в ней хорошо описано, как делать комментарии в ситуациях, когда это необходимо. (Например, объяснение сложной математической формулы)

Code Complete, как уже упоминалось, имеет различные рекомендации по написанию комментариев. Короче говоря, это PDL, и его можно суммировать как:

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

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

3. Иметь представление о том, что делает ваш код, еще до написания кода

4. Есть комментарии как можно ближе к фактическому коду

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

На GameDev.net есть ссылка [которая объясняет PDL] [1], если вы не хотите отслеживать книгу.

Я просто следую одному простому и общему принципу: в ваших комментариях должно быть указано не то, что делает код, а то, почему он это делает. В статье и книге Мартина Фаулера о рефакторинге и Code Complete в книге много информации, но, к сожалению, она не в обобщенной форме, насколько мне известно.

Мое предложение было бы написать некоторый код без каких-либо комментариев, а затем уйти от него. Вернись к нему через год и прочитай. Часть, которую вы не понимаете легко, это часть, которую вы должны были прокомментировать.

Мне очень нравится, как Эван Тодд суммирует свою точку зрения на единственные полезные категории комментариев ( цитата из его блога ):

• Комментарии, объясняющие почему, а не что. Это самые полезные.
• Комментарии с несколькими словами, объясняющими, что делает следующий гигантский кусок кода. Они полезны для навигации и чтения.
• Комментарии в объявлении структуры данных, объясняющие, что означает каждое поле. Часто они не нужны, но иногда невозможно интуитивно отобразить концепцию в памяти, и для описания сопоставления необходимы комментарии.