Роберт Мартин - Чистый код. Создание, анализ и рефакторинг

Следующий код взят из общих модулей Apache:

this.bytePos = writeBytes(pngIdBytes, 0);

//hdrPos = bytePos;

writeHeader();

writeResolution();

//dataPos = bytePos;

if (writeImageData()) {

writeEnd();

this.pngBytes = resizeByteArray(this.pngBytes, this.maxPos);

}

else {

this.pngBytes = null;

}

return this.pngBytes;

Почему эти две строки кода закомментированы? Они важны? Их оставили как напоминание о будущих изменениях? Или это «хлам», который кто-то закомментировал сто лет назад и не удосужился убрать из программы?

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

Как видно из следующего фрагмента, HTML в комментариях к исходному коду выглядит отвратительно. Он затрудняет чтение комментариев именно там, где они должны легко читаться — в редакторе/IDE. Если комментарии должны извлекаться внешним инструментом (например, Javadoc) для отображения в веб-странице, то за украшение комментариев соответствующим кодом HTML должен отвечать этот инструмент, а не программист.

/**

* Задача для запуска тестов.

* Задача запускает тесты fitnesse и публикует результаты.

*

*

*/

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

/**

* Порт, на котором будет работать fitnesse. По умолчанию 8082.

*

* @param fitnessePort

*/

public void setFitnessePort(int fitnessePort)

{

this.fitnessePort = fitnessePort;

}

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

/*

RFC 2045 - Multipurpose Internet Mail Extensions (MIME)

Часть 1: Формат тел сообщений

раздел 6.8. Кодирование данных Base64

В процессе кодирования 24-разрядные группы входных битов представляются

в виде выходных строк из 4 закодированных символов. Слева направо 24-разрядная

входная группа образуется посредством конкатенации 38-разрядных входных групп.

Далее эти 24 бита интерпретируются как 4 конкатенированных 6-разрядных группы,

каждая из которых преобразуется в одну цифру алфавита base64. При кодировании

потока битов в кодировке base64 предполагается, что битовый поток упорядочивается

от старшего значащего бита. Иначе говоря, первым битом потока будет старший бит

первого 8-битового байта, а восьмым - младший бит первого 8-битого байта и т.д.

*/

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

/*

* Начать с массива, размер которого достаточен для хранения

* всех пикселов (плюс байты фильтра), плюс еще 200 байт

* для данных заголовка

*/

this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];