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

Ответ 1

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

Думаю, можно с уверенностью сказать, что все ошибки вызваны, когда код не делает то, что он должен делать:). Поэтому, если мы добавим некоторые ключевые комментарии, чтобы предоставить сопровождающим достаточно информации, чтобы знать, что должен делать кусок кода, мы дали им возможность исправить множество ошибок.

Это оставляет нам вопрос о том, сколько комментариев ввести. Если вы вкладываете слишком много комментариев, все становится утомительным для поддержания, и комментарии неизбежно будут устаревшими с кодом. Если вы вкладываете слишком мало, то они не особенно полезны.

Я нашел регулярные комментарии наиболее полезными в следующих местах:

1) Краткое описание в верхней части файла .h или .cpp для класса, объясняющего цель класса. Это помогает быстро найти обзор, не просеивая весь код.

2) Блок комментариев перед реализацией нетривиальной функции, объясняющей ее цель и детализируя ожидаемые входы, потенциальные выходы и любые странности, которые следует ожидать при вызове функции. Это спасает будущих сопровождающих от необходимости расшифровать целые функции, чтобы понять это.

Кроме этого, я склонен комментировать все, что может показаться кому-то непонятным или странным. Например: "Этот массив основан на 1 вместо 0 из-за бла-бла".

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

Ответ 2

Мне всегда нравилось, что Refactoring принимает комментарии:

Причина упоминания здесь заключается в том, что комментарии часто используются в качестве дезодоранта. Удивительно, как часто вы смотрите на комментированный код и замечаете, что комментарии есть, потому что код плохой.

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

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

Ответ 3

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

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

Документируйте контракт каждой функции и для каждого типа объекта, что он представляет, и какие-либо ограничения на допустимое представление (технически, функция абстракции

Я не всегда делаю то, что говорю здесь; это зависит от того, насколько я ценю код и кого я ожидаю прочитать. Но научиться писать таким образом сделало меня лучшим программистом даже при резке углов.

Вернемся к утверждению, что мы документируем ради локального понимания: что делает эта функция?

def is_even(n): return is_odd(n-1)

Проверяет, четное ли целое число? Если is_odd() проверяет, является ли целое число нечетным, то да, это работает. Предположим, что у нас было это:

def is_odd(n): return is_even(n-1)

То же рассуждение говорит, что это is_odd() проверяет, является ли целое число нечетным. Разумеется, их объединяют, и ни одна из них не работает, хотя каждая из них работает, если другая делает. Измените его немного, и у нас будет код, который действительно работает, но только для натуральных чисел, хотя он по-прежнему локально похож на целые. В микромире понимание того, что понимает кодовая база: трассировка зависимостей вокруг в кругах, чтобы попытаться перепроектировать предположения, которые автор мог бы объяснить в строке или двух, если бы они беспокоились. Я ненавижу расходы на бездумные кодеры, которые заставляют меня таким образом за последние несколько десятилетий: о, этот метод выглядит так, как будто он имеет побочный эффект, далекий от варпкора... всегда? Ну, если нечетные кробункулы обесцветить, по крайней мере; не так ли? Лучше проверьте весь код обработки crobuncle... который будет создавать свои собственные проблемы для понимания. Хорошая документация разрезает этот O (n) указатель-преследование до O (1): например. зная контракт о функциях и контракты, которые он явно использует, код функции должен иметь смысл, не зная системы. (Здесь контракты, говорящие is_even() и is_odd(), работают над натуральными числами, скажут нам, что обе функции должны тестироваться на n==0.)

Ответ 4

Мое единственное реальное правило заключается в том, что комментарии должны объяснять, почему код существует, а не то, что он делает или как он это делает. Эти вещи могут измениться, и если они сделают, комментарии должны быть сохранены. Назначение кода в первую очередь не должно меняться.

Ответ 5

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

strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();

кто знает, для чего это чертовски? но с простым комментарием, все раскрывается:

//when under attack, sidestep and retaliate with rocket bundles
strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();

серьезно, комментарии объясняются тем, почему, а не как, если только это неинтуитивно.

Ответ 6

Хотя я согласен с тем, что код должен быть читаемым самостоятельно, я по-прежнему вижу большую ценность в добавлении обширных блоков комментариев для объяснения проектных решений. Например: "Я сделал xyz вместо обычной практики abc из-за этого caveot..." с URL-адресом отчета об ошибке или что-то в этом роде.

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

Ответ 7

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

Ответ 8

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

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

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

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

Ответ 9

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

EDIT: Это звучало немного помпезно, но я думаю, что слишком многие люди забывают, что даже имена переменных или структуры, которые мы используем в коде, - это просто "теги" - они имеют для нас только смысл, потому что наши мозги видят строку символов, например customerNumber, и понимают, что это номер клиента. И хотя верно, что комментарии не имеют никакого "принудительного исполнения" компилятором, они не так уж далеки. Они предназначены для передачи смысла другому человеку, человеческому программисту, который читает текст программы.

Ответ 10

Если код не ясен без комментариев, сначала сделайте код более ясным выражением о намерениях, а затем добавьте только комментарии по мере необходимости.

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

Требование комментариев и "измерение производительности" в строках кода может привести к нежелательной почте, например:

/*****
 *
 * Increase the value of variable i,
 * but only up to the value of variable j.
 *
 *****/

if (i < j) {
    ++i;
} else {
    i = j;
}

а не кратким (и понятным для соответствующего программиста):

i = Math.min(j, i + 1);

YMMV

Ответ 11

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

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

Ответ 12

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

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

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

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

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

Ответ 13

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

Ответ 14

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

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

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

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

... чтение кода скажет вам точно что он делает. Однако код неспособный сказать вам, что это такое предположительно.

Ответ 15

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

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

Ответ 16

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

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

Ответ 17

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

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

Ответ 18

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

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

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

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

Ответ 19

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

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

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

Ответ 20

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

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

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

Ответ 21

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

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

Ответ 22

Здесь мой взгляд (основанный на нескольких годах докторских исследований):

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

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

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

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

Ответ 23

Я прокомментирую столько, сколько необходимо - тогда, сколько мне понадобится год спустя.

Ответ 24

Мы добавляем комментарии, которые предоставляют справочную документацию по API для всех общедоступных классов/методов/свойств/и т.д. Это стоит того, что XML Documentation на С# имеет приятный эффект от предоставления IntelliSense пользователям этих общедоступных API. Кодовые контракты .NET 4.0 позволят нам еще больше улучшить эту практику.

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

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

Ответ 25

Мой подход:

Комментарии перекрывают пробел между контекстом/реальным миром и кодом. Поэтому каждая отдельная строка прокомментирована на правильном английском языке.

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

Использование хорошо отформатированных XML-комментариев самоочевидно.

Sloppy commenting означает неаккуратный код!

Ответ 26

Вот как я написал код:

if (hotel.isFull()) {
    print("We're fully booked");
} else {
    Guest guest = promptGuest();
    hotel.checkIn(guest);
}

вот несколько комментариев, которые я мог бы написать для этого кода:

// if hotel is full, refuse checkin, otherwise 
// prompt the user for the guest info, and check in the guest.

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

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