Вводные комментарии

Комментарии

Стандартизация стиля

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

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

Желательность комментариев, казалось бы, очевидна, однако далеко не всегда их включают в программу. Комментарии опускают с целью экономии времени. Иногда утверждают, что "комментарии будут вставлены позже". Но такая отговорка неубедительна, потому что через удивительно короткое время авторы программы обнаруживают, что забыли многие детали.

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

Одна из причин отсутствия комментариев - переоценка наших возможностей. Мы уверены, что легко вспомним логику той или иной части программы. Более того, мы не ожидаем большого количества ошибок в нашей программе, и комментарии кажутся нам излишними. Однако опыт говорит об обманчивости подобных ожиданий.

Отсутствие комментариев затрудняет тестирование и отладку, а также является свидетельство дилетантского подхода.

Рекомендуется включать комментарии в процессе написания программы. Именно в это время вы в наибольшей степени вникаете во все детали программы. Редко удается получить удовлетворительные результаты при более поздней вставке комментариев: при этом приходится вспоминать, что следует прокомментировать.

Делайте комментариев больше, чем это кажется необходимым.

Существуют три типа комментариев:

· вводные,

· оглавления,

· пояснительные.

Каждая программа, подпрограмма или процедура должна начинаться с комментариев, поясняющих, что она делает. Вводные комментарии могут включать следующие пункты:

1. Назначение программы.

2. Указания по вызову программы и ее использованию.

3. Список и назначение основных переменных или массивов.

4. Указания по вводу-выводу. Список всех файлов.

5. Список используемых подпрограмм.

6. Название применяемых математических методов, а также ссылки на литературные источники, где содержится их описание.

7. Сведения о времени выполнения программы.

8. Требуемый объем памяти.

9. Специальные указания оператору.

10. Сведения об авторе.

11. Дата написания программы.

Делайте вводные комментарии