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

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

  {

  }

}

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

Опасный шум

Комментарии Javadoc тоже бывают «шумовыми». Какую пользу приносят следующие комментарии (из хорошо известной библиотеки, распространяемой с открытым кодом)? Ответ: никакой. Это избыточные шумовые комментарии, вызванные неуместным желанием как-то документировать свои действия.

/** Имя. */

private String name;

/** Версия. */

private String version;

/** Название лицензии. */

private String licenceName;

/** Версия. */

private String info;

Прочитайте эти комментарии повнимательнее. Заметили ошибку копирования/вставки? Если авторы не следят за ними в момент написания (или вставки), то как можно ожидать, что эти комментарии принесут пользу читателю?

Не используйте комментарии там, где можно использовать функцию или переменную

Возьмем следующий фрагмент кода:

// Зависит ли модуль из глобального списка от подсистемы,

// частью которой является наш код?

if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

Его можно было бы перефразировать без комментария в следующем виде: