Комментарии. Не нужны даже для документации?
Роберт Мартин в книге "Чистый код" пишет
А теперь рассмотрим легион бесполезных, избыточных комментариев 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 шт):
У любого комментария одна задача: сделать так, чтобы любой программист понял суть вашей программы, что и как она делает. Если какой то кусок кода делает абсолютно очевидную вещь, то и комментировать ее ни к чему. Нужно просто быть осторожным, ведь для вас, вовлеченного в программу на данный момент времени, очевидными могут быть и те моменты, которые другой кодер не поймет. Смотрите на код со стороны незамыленным глазом, и если потребуется лишнее время для понимания его работы, то ему определенно требуется комментарий
Наверное, я напишу примерно тоже, что написано в другом ответе, но всё-таки:
- Очевидные вещи комментировать не нужно:
- Не нужно расшифровывать в комментариях "говорящие имена" полей, методов, классов и т.п.
- Не нужно комментировать, что делает каждая строчка кода
- Что же тогда комментировать:
- Код, который с виду не кажется логичным/правильным/уместным, если он так написан намеренно - самое то объяснить в комментарии, почему код именно такой, чтобы потом при рефакторинге в "нормальный код" не было сюрприза
- Если есть какая-то внешняя документация по сложному классу/методу, то можно дать на неё ссылку в комментарии
Ну это так, вкратце.