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

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

*/

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

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

         /*

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

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

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

          */

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

Что такое «байты фильтра»? Они как-то связаны с +1? Или с *3? И с тем и с другим? Один пиксел соответствует одному байту? И почему 200? Цель комментария — объяснить код, который не объясняет сам себя. Плохо, когда сам комментарий нуждается в объяснениях.

Заголовки функций

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

Заголовки Javadoc во внутреннем коде

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

Пример

Модуль в листинге 4.7 был написан для первого учебного курса «XP Immersion». Предполагалось, что он является примером плохого кодирования и стиля комментирования. Кент Бек переработал этот код в куда более приятную форму перед несколькими десятками увлеченных слушателей. Позднее я приспособил этот пример для своей книги «Agile Software Development, Principles, Patterns, and Practices» и статьи в журнале «Software Development». Любопытно, что в то время многие из нас считали этот модуль «хорошо документированным». Теперь мы видим, что он представляет собой ералаш. Посмотрим, сколько разных ошибок комментирования вам удастся найти.

Листинг 4.7. GeneratePrimes.java

/**

* Класс генерирует простые числа в диапазоне до максимального значения,

*  заданного пользователем, по алгоритму "Решета Эратосфена".

*

* Эратосфен Киренский, 276 год до н.э., Ливия --  * 194 год до н.э., Александрия.

* Первый ученый, вычисливший длину земного меридиана. Известен своими работами

* о календарях с високосным годом, заведовал Александрийской библиотекой.

*

* Алгоритм весьма прост. Берем массив целых чисел, начиная с 2, и вычеркиваем

* из него все числа, кратные 2. Находим следующее невычеркнутое число

* и вычеркиваем все его кратные. Повторяем до тех пор, пока не дойдем

* до квадратного корня верхней границы диапазона.

*

* @author Альфонс

* @version 13 февраля 2002 u

*/

import java.util.*;

public class GeneratePrimes

{

  /**

   * @param maxValue - верхняя граница диапазона.

   */

  public static int[] generatePrimes(int maxValue)

  {

    if (maxValue >= 2) // Единственно допустимый случай

    {

      // Объявления

      int s = maxValue + 1; // Размер массива

      boolean[] f = new boolean[s];

      int i;

      // Инициализировать массив значениями true.

      for (i = 0; i < s; i++)

        f[i] = true;

      // Удалить числа, заведомо не являющиеся простыми.

      f[0] = f[1] = false;

      // Отсев

      int j;

      for (i = 2; i < Math.sqrt(s) + 1; i++)

      {

        if (f[i]) // Если элемент i не вычеркнут, вычеркнуть кратные ему.

        {

          for (j = 2 * i; j < s; j += i)