32.4. Советы по эффективному комментированию

Пока существуют плохо опрвде- следующий метод?

ленные цели» странные ошибки . /, v

и нереалистичные сроки, будт Загадочный метод номер один (Java)

сущесшеать и Настоящие про- У g п от i до num

грашисты, желающие немедленно приступить к Решению Проблемы и оставляющие документацию на потом. Да адрае-

current = 1; previous = 0; sun = 1;

ствует Фортран] ( int i - 0; i < num; i++ ) {

За Пост (EdPost) System.out. println( "Sum = " + sum ); sum = current + previous; previous = current; current = sum;

Этот метод вычисляет первые пит чисел Фибоначчи. Стиль кодирования этого метода чуть лучше, чем стиль метода, указанного в начале главы, но комментарий неверен, и если вы слепо доверяете комментариям, то, пребывая в блаженном неведении, пойдете в неверном направлении.

А что скажете по поводу этого метода? Загадочный метод номер два (Java)

присваивание переменной "product" значения переменной "base" product = base;

цикл от 2 до "num"

for ( int i = 2; i num; i++ ) {

умножение "base" на "product"

product = product * base;

System.out.println( "Product = " + product );

Этот метод возводит целое число base в целую степень пит. Комментарии в этом методе верны, но они не говорят о коде ничего нового. Это просто более многословная версия самого кода.

Наконец, еще один метод: Загадочный метод номер три (Java)

вычисление квадратного корня из Num с помощью аппроксимации Ньютона-Рафсона г = num / 2;

while ( abs( г - (num/r) ) > TOLERANCE ) { г = 0.5 * ( г + (num/r) );

System.out.println( "r = " + r );

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

Какой метод понять было легче всего? Все они написаны довольно плохо - особенно неудачны имена переменных. По сути эти методы иллюстрируют достоинства и недостатки внутренних комментариев. Комментарий Метода 1 неверен. Комментарии Метода 2 просто повторяют код и потому бесполезны. Только комментарий Метода 3 оправдывает свое существование. Наличие плохих комментариев хуже, чем их отсутствие. Методы 1 и 2 лучше было бы оставить вообще без комментариев.

В следующих подразделах я приведу советы по написанию эффективных комментариев.

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

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

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

Объяснение кода

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

Маркер в коде

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

Мало что может сравниться с чувствами программиста, получившего от заказчика сообщение о проблеме в коде и увидевшего во время отладки что-нибудь вроде:

return NULL; ****** НЕ СДЕЛАНО! ИСПРАВИТЬ ДО ВЫПУСКА ПРОГРАММЫ!!!

Если вы поставили заказчикам дефектную программу, это плохо; если же вы знали, что она дефектна, это просто ужасно.

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

кий поиск незавершенных фрагментов одним из действий контрольного списка перед выпуском программы и предотвратить проблему ИСПРАВИТЬ ДО ВЫПУСКИ . Некоторые редакторы поддерживают теги «to do» и позволяют легко искать их.

Резюме кода

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

Описание цели кода

Комментарий уровня цели объясняет намерения автора кода. Такие комментарии относятся скорее к уровню проблемы, чем к уровню ее решения. Например, комментарий:

-- получение информации о текущем сотруднике

является комментарием цели, тогда как:

-- обновление объекта employeeRecord

является резюмирующим комментарием, сформулированным в терминах решения.

Шестимесячное исследование, проведенное в IBM, показало, что программисты, отвечавшие за сопровождение программы, «чаще всего говорили, что труднее всего было понять цель автора кода» (Fjelstad and Hamlen, 1979). Различие между комментариями цели и резюмирующими не всегда очевидно и обычно не играет особой роли. В этой главе вы найдете массу примеров комментариев цели.

Информация, которую невозможно выразить в форме кода

Кое-какую информацию, не выразимую в форме кода, все-таки нужно включить в программу Эта категория комментариев включает уведомления об авторских правах и конфиденциальности данных, номера версий и другие детали, замечания о структуре кода, ссылки на релевантные документы требований или архитектуры, ссылки на Интернет-ресурсы, соображения по оптимизации, комментарии, нужные таким инструментам редактирования, как Javadoc, Doxygen и т. д.

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

Эффективное комментирование

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

Написание комментариев может отнимать много времени по двум причинам. Во-первых, стиль комментирования может быть трудоемким или нудным. Если это