Комментарии

Цель – пояснить логику, облегчить отладку, тестирование и сопровождение программ.

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

Вопрос о количестве (объеме) комментариев является дискуссионным. Их количество зависит от сложности логики программы, числа процедур и используемых библиотечных функций, а также от того, является ли программа коллективной разработкой или нет. Можно указать такой косвенный критерий достаточности объема комментирования: объем комментариев должен быть таков, чтобы при чтении ее текста, скажем через 1 год, можно было достаточно легко разобраться в логике и структуре программы.

Можно также привести грубый количественный критерий: ориентировочный объем комментариев – 50-70% от объема кода программы.

Различают следующие типы комментариев: оглавления, вводные, пояснительные.

Оглавления. Разумно составлять для программ, объем кода которых превышает 300 – 500 КБ.

Вводные. Записываются перед началом текста процедуры. Содержание:

- функция, выполняемая процедурой;

- характеристики и особенности процедуры.

Пример.

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

/* WHEN_WHOLE_BASE */

/* Редактировать поле, если БД не разделена */

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

Пояснительные. Служат для пояснения:

- параметров и переменных при объявлении (помещаются справа от имени);

- смысла неочевидных проверок (справа от условия);

- логического фрагмента процедуры (на отдельных строках перед началом фрагмента).

Пример.

if(agpec == NULL){ /* Hесогласованная ссылка */

Принцип комментирования: программа должна быть понятна без привлечения дополнительной документации.