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

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

дакторе без расцвечивания синтаксиса. Комментарии должны легко читаться и в этом случае.

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

ему вид единого целого:

/*

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

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

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

*/

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

/*

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

несколько строк

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

*/

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

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

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

void strangeCommentStyle()

{

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

{

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

doSomethingMeaningful(n);

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

anotherUsefulOperation(n);

}

}

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

Это будет гораздо безопаснее.

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

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

class HandyExample

{

public:

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

private:

int appleCount; // Комментарии в конце строки

bool isFatherADustman; // отделите их

int favoriteNumber; // от кода

};

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

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

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

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

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

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

ми крайне уродливым образом.

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