Каков ваш личный подход / принимать комментарии?

Question

Дублирование

Каковы ваши жесткие правила комментирования?

Разработчик, с которым я работаю, хотел кое-что сказать по поводу комментариев, которые были мне интересны (см. Ниже). Каков твой персональный подход к комментированию?

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

"Я думаю, что есть несколько лагерей, когда это приходит к комментированию, типа предприятия, которые думают, что они написание API и некоторые великие библиотека кодов, которая будет использоваться для грядущие поколения подобный ремесленнику программист, который думает код говорит, что он делает яснее, чем Комментировать могли и новички, которые пишут подробный / неясный код, чтобы оставьте себе записи о том, почему они что-то сделали. "

Answer 1

Подавляющее большинство моих комнетов находятся на уровне класса и метода, и мне нравится описывать представление более высокого уровня, а не просто args / return value. Я особенно осторожен, чтобы описать любые «нелинейности» в функции (пределы, угловые случаи и т. Д.), Которые могут сбить с толку неосторожных.

Обычно я не комментирую внутри метода, за исключением пометки элементов "FIXME", или очень иногда какого-то рода "здесь быть монстрами", которые я просто не могу очистить, но я очень много работаю, чтобы избежать этого. Как говорит Фаулер в Рефакторинг , комментарии, как правило, указывают на незначительный код.

Answer 2

Я предпочитаю использовать комментарии типа "Гензель и Гретель"; небольшие заметки в коде о , почему я делаю это так или , почему какой-то другой способ не подходит . Следующим, кто посетит этот код, вероятно, понадобится эта информация, и чаще всего этим человеком будет я.

Answer 3

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

Я помню, как изучал C # и читал чужой код, я часто расстраивался из-за таких вопросов, как "какое из 9 значений символа двоеточия означает это одно значение?" Если вы не знаете название функции, как вы ее ищите ?! (Примечание: это была бы хорошая функция IDE: я выбираю оператор или другой токен в коде, щелчок правой кнопкой мыши затем показывает мне его языковую часть и имя функции. Это нужно C #, VB меньше.)

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

И мне нравится @ 17 из 26 комментариев (добавлено empahsis):

... чтение кода скажет вам точно что он делает . Тем не менее, код неспособен сказать вам, что это предполагается делать.

Answer 4

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

В общем, при программировании вы должны делать вещи только один раз в одном месте.

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

Однако, если потребуется дальнейшее объяснение, я добавлю комментарий с префиксом INFO, NOTE и аналогичным ...
ИНФОРМАЦИЯ: комментарий предназначен для общей информации, если кто-то незнаком с этой областью.
ПРИМЕЧАНИЕ. Комментарий предназначен для предупреждения о потенциальной странности, такой как странное бизнес-правило / реализация.
Если я не хочу, чтобы люди касались кода, я могу добавить ПРЕДУПРЕЖДЕНИЕ: или аналогичный префикс.

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

Answer 5

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

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

Answer 6

Я очень очень редко комментирую. Моя теория, если вы должны комментировать, это потому, что вы не делаете вещи наилучшим образом. Как «работа вокруг» это единственное, что я хотел бы прокомментировать. Потому что они часто не имеют смысла, но есть причина, по которой вы делаете это, поэтому вам нужно объяснить.

Комментарии являются признаком подпункта кода IMO. Я твердо верю в самодокументированный код. Большая часть моей работы может быть легко переведена, даже неспециалистом, из-за описательных имен переменных, простой формы, точных и многих методов (IOW не имея методов, которые делают 5 разных вещей).

Answer 7

Комментарии являются частью набора инструментов для программистов и могут использоваться и злоупотреблять. Не вам, другому программисту или кому-то другому действительно сказать, что один инструмент в целом плох. Есть места и время для всего, включая комментарии.

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

Answer 8

Вот мое мнение (на основе нескольких лет докторских исследований):

Существует огромная разница между функциями комментирования (вроде использования черного ящика, например JavaDocs) и комментированием реального кода для того, кто будет читать код ("внутреннее комментирование").

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

Теперь комментарии к функциям действительно являются проблемой, и в некотором смысле ваш друг прав, что для большей части кода нет экономического стимула для полных спецификаций, как документирование популярных API. Здесь важно определить, что такое «директивы»: директивы - это те информационные фрагменты, которые напрямую влияют на клиентов и требуют каких-то прямых действий (и часто являются неожиданными). Например, X должен быть вызван до Y, не вызывайте его извне потока пользовательского интерфейса, помните, что это имеет определенный побочный эффект и т. Д. Это то, что действительно важно захватить.

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

Answer 9

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

Я также пытаюсь дать заголовки документации по методам и классам, что хорошо для intellisense и автоматически сгенерированной документации. У меня действительно плохая привычка оставлять 90% моих методов и классов без документов. У вас нет времени документировать вещи, когда вы занимаетесь программированием, и все постоянно меняется. Затем, когда вы закончите, вам не хочется возвращаться и находить все новые вещи и документировать их. Вероятно, хорошо возвращаться каждый месяц или около того и просто написать кучу документации.

Answer 10

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

Так что в этом случае комментирование кажется излишним:

/*
 * this function adds two integers
 */
int add(int x, int y)
{
    // add x to y and return it
    return x + y;
}

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