Правила программирования на С и С++. Главы 1-6 - Комментарий должен предоставлять только нужную для сопровождения информацию
ОГЛАВЛЕНИЕ
27. Комментарий должен предоставлять только нужную для сопровождения информацию.
Особенно неприятным и бесполезным комментарием является декларативный заголовочный блок. Заголовок сам по себе не является злом, а совсем наоборот. Блок комментариев в начале файла, описывающий что делается в файле, может быть довольно полезен. Хороший блок говорит вам, какое свойство реализуется файлом, показывает список открытых (не статических) функций, сообщает вам, что эти функции делают и т.д.
Заголовки, которые мне не нравятся, имеют содержание, которое определяется указанием, обычно типа какого-то руководства по фирменному стилю. Такие заголовки обычно выглядят подобно листингу 1, увеличивая беспорядок посредством обильных количеств бесполезной информации за счет читаемости. Часто случается так, как на листинге 1, когда заголовок существенно больше самой программы. Также обычно, как в нашем случае, что текст программы или совершенно самодокументирован, или нужно добавить одну или две строки комментариев, чтобы он им стал. Хотя требование вышеуказанной бессмыслицы и может согревать душу деспота-руководителя, но для облегчения сопровождения оно мало что дает.
Листинг 1. Бесполезный заголовочный комментарий.
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** |
| |
| |
| |
| |
|