Главная » Java, Советы » Для всех открытых элементов АРI пишите dос – комментарии

0

 

Если АРI будет использоваться, его нужно описывать. Обычно документация к АРI пишется вручную, и поддержание соответствия между документацией и программным кодом – весьма неприятная работа. Среда программирования Java облегчает эту задачу с помощью утилиты, называемой /avadoc. Она автоматически генерирует документацию к API, отталкиваясь от исходного текста программы, дополненного специальным образом оформленными комментариями к документации (documentation comment), которые чаще называют dос – комментариями (doc comment). Утилита Javadoc предлагает простой, эффективный способ документирования АРI и используется повсеместно.

Если вы еще не знакомы с соглашениями для dос – комментариев, то обязаны их изучить. Эти соглашения не являются частью языка программирования Java, но де-факто они образуют свой API, который обязан знать каждый программист. Соглашения сформулированы в "The Javadoc Tool Ноте Page" [Javadoc-b].

Чтобы должным образом документировать API, следует предварять doc – комментарием каждую предоставляемую пользователям декларацию класса, интерфейса, конструктора, метода и поля. Единственное исключение обсуждается в конце статьи. Если dос – комментарий отсутствует, самое лучшее, что может сделать Javadoc,- это воспроизвести декларацию элемента АРI как единственно возможную для него документацию. Работа с API, у которого нет комментариев к документации, чревата ошибками. Чтобы создать программный код, приемлемый для сопровождения, вы должны написать dос – комментарии даже для тех классов, интерфейсов, конструкторов, методов и полей, которые не предоставляются пользователям.

Dос – комментарий для метода должен лаконично описывать соглашения между методом и его клиентами. Соглашение должно оговаривать, что делает данный метод, а не как он это делает. Исключение составляют лишь методы в классах, предназначенных для наследования (статья 15). В dос – комментарии необходимо перечислить все предусловия (precondition), т. е. утверждения, которые должны быть истинными для того, чтобы клиент мог вызвать этот метод, и постусловия (postcondition), т. е. утверждения, которые будут истинными после успешного завершения вызова. Обычно предусловия неявно описываются тегами @throws для необработанных исключений. Каждое необработанное исключение соответствует нарушению некоего предусловия. Предусловия также могут быть указаны вместе с параметрами, которых они касаются, в соответствующих тегах @раrаm.

Помимо пред- и постусловий для методов должны быть также документированы любые побочные эффекты. Побочный эффект (side effect) – это поддающееся наблюдению изменение состояния системы, которое является неявным условием для достижения постусловия. Например, если метод запускает. фоновый поток, это должно быть отражено в документации. Наконец, комментарии к документации должны описывать безопасность класса при работе с потоками (thread safety) , которая обсуждается в статье 52.

В целях полного описания соглашений dос – комментарий для метода должен включать в себя: тег @ракаm для каждого параметра, тег @return, если только метод не возвращает тип void, и тег @throws для каждого исключения, инициируемого этим методом, как обработанного, так инеобработанного (статья 44). По соглашению, текст, который следует за тегом @раrаm или @return, представляет собой именную конструкцию (noun phrase – термин грамматики английского языка). Описывающую значение данного параметра или возвращаемое значение. Текст, следующий за тегом @throws, должен состоять из слова if и именной конструкции, описывающей условия, при которых инициируется данное исключение. Иногда вместо именных конструкций используются арифметические выражения. Все эти соглашения иллюстрирует следующий краткий dос – комментарий из интерфейса List:

/**

* Возвращает элемент, который занимает заданную позицию

* в указанном списке.

            * @param index – индекс элемента, который нужно возвратить; индекс должен  

            *                             быть неотрицательным, и его значение должно быть           

            *                             меньше размера списка.

            * @return             элемент, занимающий в списке указанную позицию. 

            * @throws            IndexOutOfBoundsException, если индекс лежит вне диапазона.

            *                            (<tt> index &lt; ()  || index &gt; = this.size()</tt>)

 */

Object get(int index);

 

Заметим, что в этом dос – комментарии используются метасимволы и теги языка HTML. Утилита Javadoc преобразует dос-комментарии в код HTML, и любые содержавшиеся в dос – комментариях элементы HTML оказываются в полученном НТМL – документе. Иногда программисты заходят настолько далеко, что встраивают в свои dос – комментарии таблицы HTML, хотя это не является общепринятым. Чаще 128

всего применяются следующие теги: <р> для разделения параграфов, <code> и <tt> для представления фрагментов кода, <рге> для более длинных фрагментов кода.

Теги <code> и <tt> в значительной степени эквивалентны. Тег <code> используется чаще и, согласно спецификации HTML 4.01, является более предпочтительным, поскольку <tt> – это элемент стилевого оформления шрифта. (Пользоваться элементами стилевого оформления шрифтов здесь не рекомендуется, предпочтение отдается каскадным таблицам стилей [HTML401]). Некоторые программисты все же предпочитают тег <tt>, поскольку он короче и не столь агрессивен.

Не забывайте, что для генерации метасимволов HTML, таких как знак "меньше" «), знак "больше" (» и амперсанд (&), необходимы еsсаре – последовательности. Чтобы получить знак "меньше", используйте еsсаре – последовательность "&lt; ", знак "больше" – последовательность "&gt; ", знак амперсанда – последовательность "&аmр; ". В предыдущем dос – комментарии еsсаре -последовательность применена в теге @throws.

Наконец, отметим появление в dос – комментарии слова "this". По соглашению, слово "this" всегда ссылается на тот объект, которому принадлежит вызываемый метод, соответствующий данному dос – комментарию.

Первым предложением любого dос – комментария является общее описание (summary description) того элемента, к которому этот комментарий относится. Общее описание должно позиционироваться как описывающее функции соответствующей сущности. Во избежание путаницы никакие два члена или конструктора в одном классе или интерфейсе не должны иметь одинакового общего описания. Особое внимание обращайте на перезагруженные методы, описание которых часто хочется начать с одного и того же предложения.

Внимательно следите за тем, чтобы в первом предложении dос – комментария не было точки. В противном случае общее описание будет завершено прежде времени. Например, комментарий к документации, который начинается с фразы "A college degrее, such as В. S., М. S., оr Ph. D. ", приведет к появлению в общем описании фразы "А college degree, sиch as В." Во избежание подобных проблем лучше не использовать в общем описании сокращений и десятичных дробей. Для получения символа точки нужно заменить его числовым представлением (nиmeric encoding) "&#46; ". Хотя это работает, исходный текст про граммы приобретает не слишком красивый вид:

 

  /**

* A college degree, such as В&#46;S&#46;, М&#46;S&#46; оr

* Ph&#46;D.

*/

public class Degrее { … }

 

Тезис, что первым предложением в doc – комментарии является общее описание, отчасти вводит в заблуждение. По соглашению, оно редко бывает законченным предложением. Общее описание методов и конструкторов должно представлять собой

 

 

 

глагольную конструкцию (verb phrase – термин грамматики английского языка), которая описывает операцию, осуществляемую этим методом. Например:

 

·         ArrayList(int initialCapacity) – создает пустой список с заданной начальной емкостью.

·         Collection. size() – возвращает количество элементов в указанной коллекции.

 

Общее описание классов, интерфейсов и полей должно быть именной конструкцией, описывающей сущность, которую представляет экземпляр этого класса, интерфейса или само поле. Например:

 

·         ТimerTask – задача, которая может быть спланирована классом Тiтeг для однократного или повторяющегося исполнения.

·         Math.РI – значение типа double, наиболее близкое к числу (отношение длины окружности к ее диаметру).

 

В этой статье рассмотрены лишь основные соглашения, касающиеся doc – комментариев, существует целый ряд других соглашений. Имеется несколько руководств по стилю написания dос – комментариев [Javadoc-a, VermeulenOO]. Есть также утилиты, проверяющие соблюдение этих правил [Qoclint].

Начиная с версии 1.2.2, утилита Javadoc имеет возможность "автоматически использовать вновь" и "наследовать" комментарии к методам. Если метод не имеет dос – комментария, Javadoc находит среди приемлемых наиболее близкий dOc-комментарий, отдавая при это предпочтение интерфейсам, а не суперклассам. Подробности алгоритма поиска комментариев приводятся в "The Javadoc Manual".

Это означает, что классы могут заимствовать dос – комментарии из реализуемых ими интерфейсов вместо того, чтобы копировать комментарии у себя. Такая возможность способна сократить или вовсе снять бремя поддержки многочисленных наборов почти идентичных dос – комментариев, но у нее есть одно ограничение. Наследование dос – комментариев слишком бескомпромиссно: наследующий метод никак не может поменять унаследованный doc – комментарий. Между тем метод нередко уточняет соглашения, унаследованные от интерфейс и в этом случае он действительно нуждается в собственном dос – комментарии.          

Простейший способ уменьшить вероятность появления ошибок в комментариях к документации – это пропустить НТМL – файлы, сгенерированные утилитой Javadoc, через программу проверки кода HTML (HTML validity checker). При этом будет обнаружено множество случаев неправильного использования тегов и метасимволов HTML, которые нужно исправить. Некоторые из программ проверки кода HTML, например шеbliпt [WebIint], доступны в Интернете.

Следует привести еще одно предостережение, связанное с комментариями к документации. Комментарии должны сопровождать все элементы внешнего API, но этого не всегда достаточно. для сложных API, состоящих из множества взаимосвязанных 130

классов, комментарии к документации часто требуется дополнять внешним документом, описывающим общую архитектуру данного API. Если такой документ существует, то комментарии к документации в соответствующем классе или пакете должны ссылаться на него.

Подведем итоги. Комментарии к документации – самый лучший, самый Эффективный способ документирования API. Написание комментариев нужно считать обязательным для всех элементов внешнего API. Выберите стиль, который не противоречит стандартным соглашениям. Помните, что в комментариях к документации можно использовать любой код HTML, причем метасимволы HTML необходимо маскировать еsсаре – последовательностями.

 

Источник: Джошуа Блох, Java TM Эффективное программирование, Издательство «Лори»

По теме:

  • Комментарии