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

/**

*

* @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);

* 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)

{

}

}

Искушение создать очередной «шумовой комментарий» следует заменить решимостью очистить код. Вы сами увидите, что это сделает вашу работу более приятной и эффективной.