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);
* 29.05.2003 : Исправление ошибки в методе addMonths (DG);
* 04.09.2003 : Реализация Comparable. Обновление isInRange javadocs (DG);
* 05.01.2005 : Исправление ошибки в методе addYears() (1096282) (DG);
Когда-то создание и сопровождение журнальных записей в начале каждого модуля было оправдано. У нас еще не было систем управления исходным кодом, которые делали это за нас. В наши дни длинные журналы только загромождают и усложняют код. Их следует полностью удалить из ваших программ.
Шум
Также в программах нередко встречаются комментарии, не содержащие ничего, кроме «шума». Они лишь утверждают очевидное, не предоставляя никакой новой информации.
/**
* Конструктор по умолчанию.
*/
protected AnnualDateRule() {
}
Да неужели? А как насчет этого:
/** День месяца. */
private int dayOfMonth;
И наконец, апофеоз избыточности:
/**
* Возвращает день месяца.
*
* @return день месяца.
*/
public int getDayOfMonth() {
return dayOfMonth;
}
Эти комментарии настолько бесполезны, что мы учимся не обращать на них внимания. В процессе чтения кода наш взгляд просто скользит мимо них. Рано или поздно код вокруг таких комментариев изменяется, и они начинают лгать.
Первый комментарий в листинге 4.4 кажется уместным. Он объясняет, почему блок catch игнорируется. Но второй комментарий не несет полезной информации. Видимо, программист настолько вышел из себя при написании этих блоков try/catch в этой функции, что ему понадобилось «выпустить пар».
private void startSending()
{
try
{
doSending();
}
catch(SocketException e)
{
// Нормально. Кто-то прервал запрос.
}
catch(Exception e)
{
try
{
response.add(ErrorResponder.makeExceptionString(e));
response.closeAll();
}
catch(Exception e1)
{
// Ну хватит уже!
}
}
}
Вместо того чтобы давать выход чувствам в бесполезном комментарии, программисту следовало понять, что раздражение можно было снять улучшением структуры кода. Ему стоило направить свою энергию на выделение последнего блока try/catch в отдельную функцию, как показано в листинге 4.5.
private void startSending()
{
try
{
doSending();
}
catch(SocketException e)
{
// Нормально. Кто-то прервал запрос.
}
catch(Exception e)
{
addExceptionAndCloseResponse(e);
}
}
private void addExceptionAndCloseResponse(Exception e)
{
try
{
response.add(ErrorResponder.makeExceptionString(e));
response.closeAll();
}
catch(Exception e1)