Комментарии. Не нужны даже для документации?

Роберт Мартин в книге "Чистый код" пишет

А теперь рассмотрим легион бесполезных, избыточных комментариев Javadoc из листинга 4.2, позаимствованных из Tomcat. Эти комментарии только загромождают код и скрывают его смысл. Никакой пользы для документирования от них нет. Что еще хуже, я привел только несколько начальных комментариев — в этом модуле их намного больше.

public abstract class ContainerBase
 implements Container, Lifecycle, Pipeline,
 MBeanRegistration, Serializable {
 /**
 * Задержка процессора для этого компонента.
 */
 protected int backgroundProcessorDelay = -1;
 /**
 * Поддержка событий жизненного цикла для этого компонента.
 */
 protected LifecycleSupport lifecycle =
 new LifecycleSupport(this);
 /**
 * Слушатели контейнерных событий для этого контейнера.
 */
 protected ArrayList listeners = new ArrayList();
 /**
 * Реализация загрузчика, связанная с контейнером.
 */
 protected Loader loader = null;
 /**
 * Реализация журнального компонента, связанная с контейнером.
 */
 protected Log logger = null;
 /**
 * Имя журнального компонента.
 */
 protected String logName = null;
 /**
 * Реализация менеджера, связанная с контейнером.
 */
 protected Manager manager = null;
 /**
 * Кластер, связанный с контейнером.
 */
 protected Cluster cluster = null;
 /**
 * Удобочитаемое имя контейнера.
 */
 protected String name = null;
88
Плохие комментарии   89
 /**
 * Родительский контейнер, по отношению к которому
 * данный контейнер является дочерним.
 */
 protected Container parent = null;

 ... и т.д.

У меня два-три вопроса: получается что, если имена сами за себя говорят, то не надо комментировать, даже если это будет использоваться для доументации? Где логика?

И если имена сами за себя говорят и класс не для документации, то, получается, не надо писать комментарии?


Ответы (2 шт):

Автор решения: Рустам Нафиков

У любого комментария одна задача: сделать так, чтобы любой программист понял суть вашей программы, что и как она делает. Если какой то кусок кода делает абсолютно очевидную вещь, то и комментировать ее ни к чему. Нужно просто быть осторожным, ведь для вас, вовлеченного в программу на данный момент времени, очевидными могут быть и те моменты, которые другой кодер не поймет. Смотрите на код со стороны незамыленным глазом, и если потребуется лишнее время для понимания его работы, то ему определенно требуется комментарий

→ Ссылка
Автор решения: CrazyElf

Наверное, я напишу примерно тоже, что написано в другом ответе, но всё-таки:

  • Очевидные вещи комментировать не нужно:
    • Не нужно расшифровывать в комментариях "говорящие имена" полей, методов, классов и т.п.
    • Не нужно комментировать, что делает каждая строчка кода
  • Что же тогда комментировать:
    • Код, который с виду не кажется логичным/правильным/уместным, если он так написан намеренно - самое то объяснить в комментарии, почему код именно такой, чтобы потом при рефакторинге в "нормальный код" не было сюрприза
    • Если есть какая-то внешняя документация по сложному классу/методу, то можно дать на неё ссылку в комментарии

Ну это так, вкратце.

→ Ссылка