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

Некомментируемая программа — это, вероятно, наихудшая ошибка, которую может сделать программист, а также свидетельство дилетантского подхода (пусть даже программист имеет десятилетний опыт работы); более того, это веская причина для увольнения программиста. Последнее утверждение может показаться слишком сильным, но, вероятно, многие руководители одобрили бы его. Комментарии подобны ориентирам в незнакомом лесу. Только неразумный не оставляет ориентиров, затрудняя таким образом отладку и тестирование программы.

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

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

Хорошие комментарии написать непросто. Так как цель комментариев— облегчить понимание программы, — они должны быть так же хорошо продуманы и проработаны, как и кодировка программы. Многие комментарии могут быть перенесены из первоначальной разработки проекта, если он создается методом сверху вниз (см. гл. 2). Спецификации проекта описывают программу, и часто можно воспользоваться некоторыми из них для составлен ния комментариев. Комментарии нужны как на стадиях проектирования и отладки программы, так и позже. В связи с этим бессмысленно вставлять комментарии после того, как программа завершена. Это подобно изучению маршрута по карте после окончания путешествия. Если вы испытываете трудности при составлении комментариев для описания того, что вы делаете, то скорее всего вы "не ведаете, что творите".

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

1.2.1. ВВОДНЫЕ КОММЕНТАРИИ

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

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

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

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

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

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

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

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

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

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

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

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

Эти данные -необходимы для документирования программы, и наилучшим местом для размещения этой информации является сама программа. На рис. 1.1 показан пример подобной документации.

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

Рис. 1.1. Подпрограмма TALLY.

1.2.2. ОГЛАВЛЕНИЕ

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

Делайте оглавление в больших программах.

1.2,3. ПОЯСНИТЕЛЬНЫЕ КОММЕНТАРИИ

Пояснениями нужно сопровождать те части программы, которые трудно понять без комментариев. Перед существенными для понимания логики программы циклами или условными операторами должны появляться комментарии с указаниями действия, которое будет производиться. Надлежащим образом составленные комментарии обеспечивают словесное описание логики программы и изменения данных. Сопровождайте комментариями те действия, которые, с вашей точки зрения, могут быть не совсем понятны другому. Эта документация будет всегда находиться вместе с программой. Она поможет другому программисту понять вашу программу, а вам вспомнить написанные ранее разделы программы в в то время, когда вы работаете над ее новыми разделами. Средней нормой можно считать одну строку комментариев на десять строк программы, написанной на языке высокого уровня.

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

Считается, что программы на языках высокого уровня легка читаются и как бы сами себя документируют, однако часто логика одного программиста — автора программы — не очевидна для другого. В таких случаях (а их значительно больше, чем кажется) роль комментариев неоценима. Комментарии следует давать в таких местах программы, которые хочется пояснить, когда вы знакомите кого-либо со своей программой.

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

/* ПРОВЕРИТЬ, ЯВЛЯЕТСЯ ЛИ ВЕЛИЧИНА ОТРИЦАТЕЛЬНОЙ */

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

у* ВЫПОЛНИТЬ ОБРАБОТКУ ОТРИЦАТЕЛЬНОГО САЛЬДО (СУММАРНЫЕ РАСХОДЫ ПРЕВЫШАЮТ ДОХОДЫ.) */

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

комментарии должны содержать некоторую дополнительную информацию, а не перефразировать программу.

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

1.2.4. РАСПОЛОЖЕНИЕ КОММЕНТАРИЕВ

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

1. Чтобы поместить в этот прямоугольник комментарии.

2. Чтобы сгруппировать множество команд. Это достигается расположением до и после этой группы команд строк комментариев, заполненных специальными символами.

3. Чтобы указать, что комментарий относится к нескольким строкам программы.

Для выделения комментариев, приведенных на рис. 1.1, используются строки, состоящие из звездочек, расположенные до и после комментариев.

Если комментарии включают в строку текста программы, то используют установленную позицию (колонку) для начала каждо^

го комментария. Например, начинают комментарии с 40-й позиции, оставляя для текста программы позиции с 1-й по 39-ю. В строке комментариев для простоты распознавания желательно начинать текст комментариев, отступив от позиции начала строк операторов программы.

Для структурированных программ (гл. 2) обычно требуется меньше комментариев, чем для неструктурированных, так как программы первого вида понятнее и в них меньше переходов.

Раньше часто прибегали к комментариям, чтобы объяснить беспорядочное кодирование. Однако очевидно, что в этом случае надо не комментировать, а перепрограммировать — упорядочить программу.

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

Располагайте комментарии таким образом, чтобы это не делало ее менее наглядной.

1.2.5. ПРАВИЛЬНЫЕ КОММЕНТАРИИ

Комментарии должны быть правильными. Другими словами, они должны быть правильными сначала и изменяться в соответствии с изменениями программы. Очевидно, что неправильные комментарии— это хуже, чем их отсутствие, поскольку такие комментарии вводят в заблуждение.

Неправильные комментарии хуже, чем их% отсутствие.