каждая из которых преобразуется в одну цифру алфавита base64. При кодировании
потока битов в кодировке base64 предполагается, что битовый поток упорядочивается
от старшего значащего бита. Иначе говоря, первым битом потока будет старший бит
первого 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». Любопытно, что в то время многие из нас считали этот модуль «хорошо документированным». Теперь мы видим, что он представляет собой ералаш. Посмотрим, сколько разных ошибок комментирования вам удастся найти.
/**
* Класс генерирует простые числа в диапазоне до максимального значения,
* заданного пользователем, по алгоритму "Решета Эратосфена".
* <p>
* Эратосфен Киренский, 276 год до н.э., Ливия -- * 194 год до н.э., Александрия.
* Первый ученый, вычисливший длину земного меридиана. Известен своими работами
* о календарях с високосным годом, заведовал Александрийской библиотекой.
* <p>
* Алгоритм весьма прост. Берем массив целых чисел, начиная с 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; // Кратные числа не являются простыми.
}