7. Комментарии. Основные правила написания хороших комментариев. Комментарии todo.

КОММЕНТАРИИ

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

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

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

Хорошие комментарии написать непросто. Так как цель ком­ментариев — облегчить понимание программы, — они должны быть так же хорошо продуманы и проработаны, как и кодировка про­граммы. Существуют три типа комментариев: вводные, оглавления и пояснительные.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ПОЯСНИТЕЛЬНЫЕ КОММЕНТАРИИ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

КОММЕНТАРИИ TODO

Иногда бывает полезно оставить заметки «на будущее» в форме комментариев //TODO. В следующем примере комментарий TODO объясняет, почему функция имеет вырожденную реализацию и что она должна делать в будущем.

// T0D0 - На данный момент эта функция не используется.

// Ситуация изменится при переходе к отладочной модели.

protected Versionlnfo makeVersionO throws Exception

{

return null;

}

Комментарии TODO напоминают о том, что, по мнению программиста, сделать необходимо, но по какой-то причине нельзя сделать прямо сейчас. Например, комментарий может напомнить о необходимости удаления устаревшей функции или предложить кому-то другому поучаствовать в решении проблемы — скажем, придумать более удачное имя или внести изменения, зависящие от запланиро­ванного события. Впрочем, чем бы ни был комментарий TODO, это не повод оставлять плохой код в системе.

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