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

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

}

else {

    this.pngBytes = null;

}

return this.pngBytes;

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

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

Комментарии HTML

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

/**

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

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

*

*

* Usage:

* <taskdef name="execute-fitnesse-tests"

*     classname="fitnesse.ant.ExecuteFitnesseTestsTask"

*     classpathref="classpath" />

* OR

* <taskdef classpathref="classpath"

*             resource="tasks.properties" />

*

* <execute-fitnesse-tests

*     suitepage="FitNesse.SuiteAcceptanceTests"

*     fitnesseport="8082"

*     resultsdir="${results.dir}"

*     resultshtmlpage="fit-results.html"

*     classpathref="classpath" />

*

*/

Нелокальная информация

Если вы должны написать комментарий, проследите за тем, чтобы он описывал находящийся поблизости код. Не излагайте информацию системного уровня в контексте локального комментария. Примером служит приведенный ниже комментарий 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 предполагается, что битовый поток упорядочивается

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