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

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

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

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

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

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

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

Четкие блочные комментарии

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

Возможны несколько стратегий, особенно в отношении блочных ком% ментариев. Размещение маркеров начала и конца (т. е. /* и */ в C и C++) на отдельных строках делает блоки заметнее. Один крайний символ, пущенный по левому краю блочного комментария, придает ему вид единого целого:

/* * Такой блочный комментарий

*смотрится гораздо лучше

*внутри массива кода

*/

Это выглядит значительно лучше, чем возможная альтернатива:

/* комментарий, занимающий

несколько строк без крайнего символа. */

Во всяком случае текст комментария должен быть выровнен, а не об% разовывать зубчатую линию.

Отступы в комментариях

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

void strangeCommentStyle()

{

for (int n = 0; n < JUST_ENOUGH_TIMES; ++n)

{

//Вот полезный комментарий к следующей строке. doSomethingMeaningful(n);

//По правде, он чрезвычайно сбивает меня с толку. anotherUsefulOperation(n);

}

}

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

Комментарии в конце строки

Обычно комментарии пишут в отдельных строках, но иногда корот% кий комментарий может следовать за оператором кода в той же стро% ке. В таком случае полезно оставить пустое пространство между кодом и комментарием, чтобы четко их разграничить. Например:

class HandyExample

{

public:

... какой то открытый код ...

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

Помощь в чтении кода

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

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

Комментарии – часть повествования кода. Размещайте их так, чтобы по& рядок чтения был естественным.

Стиль должен обеспечивать легкость сопровождения

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

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

Комментарии в конце строки, рассмотренные выше, требуют опреде% ленного труда для выравнивания. Сколько усилий вы готовы на это потратить – решайте сами. Всегда приходится выбирать некий ком% промисс между приятным видом исходного кода и усилиями по его со% провождению. Я предпочитаю немного потрудиться, чтобы код не вы% глядел уродливо.

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

/******************************************************** * реализация класса foo

*********************************************************/

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

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

Тем не менее хороший выбор комментариев в качестве границ помога% ет быстро перемещаться по файлу.

Флажки

Комментарии могут также использоваться в качестве встроенных флажков в коде. Есть ряд общепринятых соглашений. В файлах, рабо% та над которыми не завершена, вы тут и там встретите //XXX, //FIXME (исправить) или //TODO (сделать). Хорошие редакторы с подсветкой синтаксиса могут выделять такие комментарии. XXX отмечает опасный или требующий переработки код. TODO часто помечает отсутствие неко% ей функциональности, которую в будущем нужно реализовать.1 FIXME указывает на фрагмент, в котором есть ошибки.

Комментарии в заголовке файла

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

1С комментариями TODO будьте осторожны. Может быть, лучше генериро% вать исключение TODO, не заметить которое нельзя. В этом случае, если вы забудете реализовать отсутствующий код, ваша программа выйдет на за%

планированный отказ в работе.

ство того, что файл создавался тщательно, а не является лишь черно% виком некоего нового кода.

Снабжайте каждый файл исходного кода прологом в виде комментария.

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

Если файл исходного кода автоматически создан в процессе сборки, необходимо каким%либо образом включить в заголовок комментарий, который четко информирует (БОЛЬШИМИ ПРОПИСНЫМИ БУКВА% МИ) об источнике происхождения файла. Иначе кто%нибудь по ошиб% ке станет его редактировать, не зная, что потеряет свой труд после оче% редной сборки.

Комментарий в нужном месте

В этой главе мы заняты в основном комментированием кода – тем, что мы фактически вводим в исходный код. Но по соседству бродят комментарии других видов:

Комментарии системы управления версиями

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

Такие комментарии очень ценны, и их нужно тщательно со% ставлять. Они должны быть:

•Краткими (для быстроты просмотра журнала модификаций)

•Точными (не ошибитесь, иначе труд бесполезен)

•Полными (чтобы знать обо всех изменениях, не прибегая к сравнению версий вручную с помощью diff)

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