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

Question

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

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

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

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

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

Answer 1

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

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

Кроме того, если я делаю что-то особым образом, что на первый взгляд выглядит неправильно, но я знаю, что это потому, что рассматриваемый код является обходным решением для платформы или чего-то в этом роде, тогда я прокомментирую ВНИМАТЕЛЬНЫЙ комментарий.

Answer 2

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

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

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

Answer 3

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

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.

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

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

Answer 4

Мой подход:

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

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

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

Небрежное комментирование означает небрежный код!

Answer 5

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

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

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

Answer 6

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