>Далее эти 24 бита интерпретируются как 4 конкатенированных 6-разрядных группы,
>каждая из которых преобразуется в одну цифру алфавита 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». Любопытно, что в то время многие из нас считали этот модуль «хорошо документированным». Теперь мы видим, что он представляет собой ералаш. Посмотрим, сколько разных ошибок комментирования вам удастся найти.
Листинг 4.7. GeneratePrimes.java
>/**
>* Класс генерирует простые числа в диапазоне до максимального значения,