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

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

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

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

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

/**

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

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

*

* Эратосфен Киренский, 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)

f[j] = false; // Кратные числа не являются простыми.

}

}

// Сколько простых чисел осталось?

int count = 0;

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

{

if (f[i])

count++; // Приращение счетчика

}

int[] primes = new int[count];

// Переместить простые числа в результат

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

{

if (f[i]) // Если простое

primes[j++] = i;

}

return primes; // Вернуть простые числа

}

else // maxValue < 2

return new int[0]; // Вернуть пустой массив при недопустимых входных данных.

}

}

В листинге 4.8 приведена переработанная версия того же модуля. Обратите внимание: применение комментариев стало намного более ограниченным. Во всем модуле осталось всего два комментария пояснительного характера.

/**

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

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

* Берем массив целых чисел, начиная с 2, и вычеркиваем

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

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

* не будут вычеркнуты все кратные.

*/

public class PrimeGenerator

{

private static boolean[] crossedOut;