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

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

Документировать необычное

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

С другой стороны, незачем комментировать очевидное. Помните: не копируйте код в комментариях!

Говорить правду

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

Быть стоящими

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

Быть понятными

Ваш комментарий должен служить аннотацией и объяснением кода. Избегайте двусмыслен-

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

свой код только хуже и затруднили его понимание.

Быть вразумительными

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

Думайте, что пишете в комментариях; не давите бездумно на клавиши.

Прочтите комментарий снова в контексте кода. Ту ли информацию он содержит?

Не отвлекаться

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

Ненужный код

Не нужно удалять код путем заключения его в комментарии. Это приводит к путанице. Даже при отладке в пожарном режиме (без штанов, без отладчика и без printfs), не прячьте код, помещая его в блок комментариев. Воспользуйтесь директивами C #ifdef 0 . . . #endif или аналогичными. Такие конструкции допускают вложенность, и их назначение более понятно (что особенно важно, если потом вы забудете сделать приборку).

Символьное художество

Избегайте ASCII -картинок и аналогичных попыток выделить код художественным образом. Вот пример неудачной идеи:

aBadExample(n, foo(wibble));

// ^^^

// Моя любимая

// функция

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

Концы блоков

Некоторые программисты помещают комментарий в конце каждого блока управления, например пишут // end if (a < 1) после закрывающей скобки оператора if. Это избыточный вид комментария; его приходится отметать, чтобы действительно понять код. Конец блока должен располагаться на той же странице, где его начало, а форматирование должно быть таким, чтобы начало и конецбыли четко видны. Любых лишних слов нужно избегать.

На практике

Проиллюстрируем принципы комментирования следующим примером. Рассмотрим фрагмент кода C++. Даже если не критиковать идиоматическую сторону, код не вполне понятен.

for (int i = 0; i < wlst.sz(); ++i)

k(wlst[i]);

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

// Итерация по всем виджетам в списке

for (int i = 0; i < wlst.sz(); ++i)

{

// Выведем этот виджет

k(wlst[i]);

}

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

for (int i = 0; i < widgets.size(); ++i)

{

printWidget(widgets[i]);

}

Обратите внимание, что я не стал переименовывать i во что-то более замысловатое. Это переменная цикла с очень небольшой областью видимости. Назвать ее loopCounter было бы излишеством и, пожалуй, затруднило бы чтение кода.

Ничего удивительного, что в итоге мы вообще остались без комментариев. Помните совет Кернигана и Плоера: плохой код нужно не комментировать, а переписывать заново. (Kernighan Plaugher 78)

Замечание об эстетичности

Несомненно, вам приходилось сталкиваться с горячими обсуждениями того, как нужно форматировать комментарии. Я не намерен наставлять вас на путь истинный в этом вопросе (его просто не существует), но есть ряд важных аспектов, которые нужно учитывать. Отнеси-

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

Единообразие

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

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