Чистый код. Создание, анализ и рефакторинг - [30]

Эта крошечная дезинформация в комментарии, который читается хуже, чем сам код, может заставить другого программиста вызвать функцию в предположении, что она вернет управление сразу же, как только значение 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);
* 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 в этой функции, что ему понадобилось «выпустить пар».

Листинг 4.4. startSending

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.

Листинг 4.5. startSending (переработанная версия)

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)
  {
  }
}

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