8. Комментарии. Основные признаки плохих комментариев. Примеры.

КОММЕНТАРИИ

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

ПЛОХИЕ КОММЕНТАРИИ

Большинство комментариев относится именно к этой категории. Обычно такие комментарии представляют собой «подпорки» для некачественного кода или оправдания сомнительных решений, а их текст напоминает рассуждения вслух самого программиста.

БОРМОТАНИЕ

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

Например, следующий фрагмент я обнаружил в FitNesse. В самом деле, ком­ментарий здесь бы пригодился. Но автор то ли торопился, то ли не придал особого значения тому, что он пишет. Его бормотание оставляет читателя в не­доумении:

public void loadPropertiesO

{

try

{

String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;

FilelnputStream propertiesStream = new FilelnputStream(propertiesPath);

loadedProperties.load(propertiesStream);

}

catchdOException e)

{

// Если нет файла свойств, загружаются настройки по умолчанию

}

}

Что означает комментарий в блоке catch? Очевидно, он что-то означал для автора, но для читателя этот смысл не доходит. Видимо, если мы получаем IOException, это означает, что файл свойств отсутствует; в этом случае должны загружаться все настройки по умолчанию. Чтобы разобраться в происходящем, нам остается только изучить код других частей системы. Любой комментарий, смысл которого приходится искать в дру­гих модулях, не несет полезной информации и не стоит битов, затраченных на его написание.

ИЗБЫТОЧНЫЕ КОММЕНТАРИИ

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

Листинг 4.1. waitForClose

// Вспомогательный метод; возвращает управление, когда значение this.closed истинно.

// Инициирует исключение при достижении тайм-аута.

public synchronized void waitForClose(final long timeoutMi11 is)

throws Exception

{

if(lclosed)

{

wait(timeoutMillis);

if(lclosed)

throw new ExceptionC'MockResponseSender could not be closed");

}

}

Какой цели достигает этот комментарий? Конечно, он несет не больше информа­ции, чем программный код. Он не объясняет код, не предоставляет обоснований и не раскрывает намерений. Он читается не проще, чем сам код.

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

Иногда с самыми лучшими намерениями программист делает в комментариях заявления, неточные и не соответствующие истине. Еще раз взгляните на со­вершенно лишний, но при этом слегка вводящий в заблуждение комментарий из листинга 4.1.

А вы нашли, в чем этот комментарий обманывает читателя? Метод не возвращает управление, когда значение this.closed становится истинным. Он возвращает управление, если значение this.closed истинно; в противном случае метод ожи­дает истечения тайм-аута, а затем инициирует исключение, если значение this.closed так и не стало истинным.

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

ОБЯЗАТЕЛЬНЫЕ КОММЕНТАРИИ

Правила, говорящие, что каждая функция должна иметь комментарий Javadoc или что каждая переменная должна быть помечена комментарием, — обычная глупость. Такие комментарии только загромождают код, распространяют недо­стоверную информацию и вызывают общую путаницу и дезориентацию.

Например, требование обязательного комментария Javadoc для каждой функции приводит к появлению монстров вроде листинга 4.3. Бессмысленные коммента­рии не приносят никакой пользы. Они только запутывают код, повышая риск обмана и недоразумений.

Листинг 4.3.

/**

*

* @param title Название диска

* @param author Автор диска

* @param tracks Количество дорожек на диске

* @param durationlnMinutes Продолжительность воспроизведения в минутах

*/

public void addCD(String title, String author.

int tracks, int durationlnMinutes) {

CD cd = new CDO;

cd.title = title;

cd.author = author;

cd.tracks = tracks;

cd.duration = duration;

cdList.add(cd);

}

ЖУРНАЛЬНЫЕ КОММЕНТАРИИ

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

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

ШУМ

Также в программах нередко встречаются комментарии, не содержащие ничего, кроме «шума». Они лишь утверждают очевидное, не предоставляя никакой новой информации.

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

НЕ ИСПОЛЬЗУЙТЕ КОММЕНТАРИИ ТАМ, ГДЕ МОЖНО ИСПОЛЬЗОВАТЬ ФУНКЦИЮ ИЛИ ПЕРЕМЕННУЮ

Возьмем следующий фрагмент кода:

// Зависит ли модуль из глобального списка <mod> от подсистемы,

// частью которой является наш код?

if (smodulе.getDependSubsystems().contains(subSysMod.getSubSystem())) Его можно было бы перефразировать без комментария в следующем виде:

ArrayList moduleDependees = smodule.getDependSubsystemsO;

String ourSubSystem = subSysMod.getSubSystemO;

i f (moduleDependees.contai ns(ourSubSystem))

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

ПОЗИЦИОННЫЕ МАРКЕРЫ

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

// Действия //////////////////////////////////

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

ССЫЛКИ НА АВТОРОВ

/* Добавлено Риком */

Системы контроля исходного кода отлично запоминают, кто и когда внес то или иное исправление. Нет необходимости загрязнять код подобными ссылками.

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

В программировании редко встречаются привычки более отвратительные, чем закрытие комментариями неиспользуемого кода. Никогда не делайте этого!

СЛИШКОМ МНОГО ИНФОРМАЦИИ

Не включайте в комментарии интересные исторические дискуссии или опи­сания подробностей, не относящиеся к делу. Следующий комментарий был извлечен из модуля, который должен был проверять, что функция кодирует и декодирует данные в формате base64. Читателю кода совершенно не нужна заумная информация, содержащаяся в этом комментарии, — вполне достаточно номера RFC.

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

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