А теперь рассмотрим легион бесполезных, избыточных комментариев Javadoc из листинга 4.2, позаимствованных из Tomcat. Эти комментарии только загромождают код и скрывают его смысл. Никакой пользы для документирования от них нет. Что еще хуже, я привел только несколько начальных комментариев — в этом модуле их намного больше.
Листинг 4.2. ContainerBase.java (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;
> /**
> * Родительский контейнер, по отношению к которому
> * данный контейнер является дочерним.
> */
> protected Container parent = null;
> /**
> * Загрузчик родительского класса, задаваемый при назначении загрузчика.
> */
> protected ClassLoader parentClassLoader = null;
> /**
> * Объект Pipeline, связанный с данным контейнером.
> */
> protected Pipeline pipeline = new StandardPipeline(this);
> /**
> * Объект Realm, связанный с контейнером.
> */
> protected Realm realm = null;
> /**
> * Объект ресурсов DirContext, связанный с контейнером
> */
> protected DirContext resources = null;
Недостоверные комментарии
Иногда с самыми лучшими намерениями программист делает в комментариях заявления, неточные и не соответствующие истине. Еще раз взгляните на совершенно лишний, но при этом слегка вводящий в заблуждение комментарий из листинга 4.1.
А вы нашли, в чем этот комментарий обманывает читателя? Метод не возвращает управление, когда значение this.closed становится истинным. Он возвращает управление, если значение this.closed истинно; в противном случае метод ожидает истечения тайм-аута, а затем инициирует исключение, если значение this.closed так и не стало истинным.