Эта крошечная дезинформация в комментарии, который читается хуже, чем сам код, может заставить другого программиста вызвать функцию в предположении, что она вернет управление сразу же, как только значение this.closed станет истинным. После этого бедный программист будет долго отлаживать программу, пытаясь понять, почему его код выполняется так медленно.
Правила, говорящие, что каждая функция должна иметь комментарий Javadoc или что каждая переменная должна быть помечена комментарием, — обычная глупость. Такие комментарии только загромождают код, распространяют недостоверную информацию и вызывают общую путаницу и дезориентацию.
Например, требование обязательного комментария Javadoc для каждой функции приводит к появлению монстров вроде листинга 4.3. Бессмысленные комментарии не приносят никакой пользы. Они только запутывают код, повышая риск обмана и недоразумений.
Листинг 4.3.
> /**
> *
> * @param title Название диска
> * @param author Автор диска
> * @param tracks Количество дорожек на диске
> * @param durationInMinutes Продолжительность воспроизведения в минутах
> */
> public void addCD(String title, String author,
> int tracks, int durationInMinutes) {
> CD cd = new CD();
> cd.title = title;
> cd.author = author;
> cd.tracks = tracks;
> cd.duration = duration;
> cdList.add(cd);
> }
Некоторые программисты добавляют комментарий в начало модуля при каждом его редактировании. Такие комментарии накапливаются, образуя своего рода журнал всех вносимых изменений. Я видел модули, в которых эти журнальные записи растягивались на десятки страниц.
>* Изменения (начиная с 11 октября 2001)
>* --------------------------
>* 11.10.2001 : Реорганизация класса и его перемещение в новый пакет
>* com.jrefinery.date (DG);
>* 05.11.2001 : Добавление метода getDescription(), устранение класса
>* NotableDate (DG);
>* 12.11.2001 : С устранением класса NotableDate IBD требует включения
>* метода setDescription() (DG); исправление ошибок
>* в методах getPreviousDayOfWeek(), getFollowingDayOfWeek()
>* и getNearestDayOfWeek() (DG);
>* 05.12.2001 : Исправление ошибки в классе SpreadsheetDate (DG);
>* 29.05.2002 : Перемещение констант месяцев в отдельный интерфейс
>* (MonthConstants) (DG);
>* 27.08.2002 : Исправление ошибки в методе addMonths() с подачи N???levka Petr (DG);
>* 03.10.2002 : Исправление ошибок по сообщениям Checkstyle (DG);
>* 13.03.2003 : Реализация Serializable (DG);