Правила программирования на С и С++. Главы 1-6
Страница 31. Комментарий должен предоставлять только нужную для сопровождения информацию

27. Комментарий должен предоставлять только нужную для сопровождения информацию.

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

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

Листинг 1. Бесполезный заголовочный комментарий.

/*-------------------------------------------------------------------------------------------	**
**	**
* ДАТА: 29 февраля 2000 г.	**
** ФУНКЦИЯ:	**
** равно	**
**	**
** АВТОР:	**
** Джозеф Эндрюс	**
**	**
** ОПИСАНИЕ:	**
** Эта функция предназначена для сравнения двух строк	**
** на лексикографическое равенство.	**
**	**
** ИСКЛЮЧЕНИЯ:	**
** Функция не работает для строк unicod.	**
**	**
** СПЕЦИАЛЬНЫЕ ТРЕБОВАНИЯ:	**
** нет.	**
**	**
** АРГУМЕНТЫ:	**
** char *s1; Указатель на первую сравниваемую строку	**
** char *s2; Указатель на вторую сравниваемую строку	**
**	**
** РЕЗУЛЬТАТЫ:	**
** Функция возвращает true, если строки-аргументы	**
** лексикографически идентичны.	**
**	**
** КОММЕНТАРИИ:	**
** нет.	**
**	**
** ПРИМЕЧАНИЯ ПО РЕАЛИЗАЦИИ:	**
** Нет.	**
**	**
** ИСТОРИЯ_ИЗМЕНЕНИЙ:	**
**	**
** АВТОР: Эндрюс, Джозеф	**
** ДАТА: 12, июль, 1743	**
** ИЗМЕНЕНИЕ: Начальное состояние	**
**	**
** АВТОР: Джонс, Том	**
** ДАТА: 13, июль, 1743	**
** ИЗМЕНЕНИЕ: Изменены имена аргументов с str1, str2.	**
**	**
** Вест текст программы в этом файле охраняется	**
** авторским правом.	**
** Copyright (c) Вымышленная корпорация	**
** Все права сохраняются.	**
**	**
** Никакая часть этой подпрограммы не может быть	**
** воспроизведена в любой форме без явного разрешения	**
** в трех экземплярах со стороны отдела министерства	**
** сокращения персонала. Нарушители будут лишены своего	**
** старшего сына.	**
**----------------------------------------------------------------------------------------	**
/*
inline equal ( char *s1, char *s2 )
{
return !strcmp(s1,s2); // Возвращает true, если строки равны.
}

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