Комментарий должен предоставлять только нужную для сопровождения информацию
Особенно неприятным и бесполезным комментарием является декларативный заголовочный блок. Заголовок сам по себе не является злом, а совсем наоборот. Блок комментариев в начале файла, описывающий, что делается в файле, может быть довольно полезен. Хороший блок говорит вам, какое свойство реализуется файлом, показывает список открытых (не статических) функций, сообщает вам, что эти функции делают и т.д.
Заголовки, которые мне не нравятся, имеют содержание, которое определяется указанием, обычно типа какого-то руководства по фирменному стилю. Такие заголовки обычно выглядят подобно листингу 1, увеличивая беспорядок посредством обильных количеств бесполезной информации за счет читаемости. Часто случается так, как на листинге 1, когда заголовок существенно больше самой программы. Также обычно, как в нашем случае, что текст программы или совершенно самодокументирован, или нужно добавить одну или две строки комментариев, чтобы он им стал. Хотя требование вышеуказанной бессмыслицы и может согревать душу деспота-руководителя, но для облегчения сопровождения оно мало что дает.
Листинг 1. Бесполезный заголовочный комментарий
/*-----------------------------------------––––––––--–--**
** **
** ДАТА: 29 февраля 2000 г. **
** ФУНКЦИЯ: **
** equal **
** **
** АВТОР: **
**
Джозеф
Эндрюс **
** **
** ОПИСАНИЕ: **
** Эта функция предназначена для сравнения двух строк **
** на лексикографическое равенство. **
** **
** ИСКЛЮЧЕНИЯ: **
** Все права сохраняются. **
** **
** Никакая часть этой подпрограммы не может быть **
** воспроизведена в любой форме без явного разрешения **
** в трех экземплярах со стороны отдела Министерства **
** сокращения персонала. Нарушители будут лишены своего **
** старшего сына. **
**------------------------------------------------------**
*/
inline equal (
char *s1, char *s2 )
{
return !strcmp( s1, s2 ); // Возвращает истину, если
} // строки равны.
Действительная проблема заключается в том, что этот тип заголовков нарушает ряд других правил, таких как: "не комментируй очевидное", "исключай неразбериху" и так далее. Тот минимум реальной информации, который содержится в этом заголовке, относится к системе регистрации изменений, а не к исходному тексту программы. Комментарии в программе должны сообщать вам сведения, полезные при сопровождении.
. Комментарии должны быть в блоках
Комментарии в общем воспринимаются лучше, когда помещаются в многострочных блоках, которые чередуются с блоками текста программы. Для этого комментарий должен описывать на высоком уровне, что делают несколько последующих строк кода. Если комментарии попадаются через строчку, то это похоже на чтение двух книг одновременно, причем по строке из каждой по очереди. И если программа, комментируемая вами, сложная, то вы можете воспользоваться сносками:
// Вот блочный комментарий, описывающий последующий блок
// программы. После общего резюме я описываю некоторые
// особенности:
//
// 1. Этот комментарий описывает, что происходит в строке
// с меткой 1
//
// 2. Этот комментарий описывает, что происходит в строке
// с меткой 2
//
// В точке 1 алгоритм устанавливается на ...
//
here_is_the_code();
while( some_condition )
{
this_code_is_rather_obscure(); /* 1 */
}
more_stuff_here();
while( some_condition )
{
this_code_is_also_obscure(); /* 2 */
}
