Для всех открытых элементов арi пишите dос - комментарии

Если АР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), т. е. утверждения, которые должны

127

быть истинными для того, чтобы клиент мог вызвать этот метод, и постусловия (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 < () || index > = 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саре - последовательность "< ", знак "больше" - последовательность "> ", знак амперсанда - последовательность "&а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) ". ". Хотя это работает, исходный текст про граммы приобретает не слишком красивый вид:

/**

* A college degree, such as В.S., М.S. оr

* Ph.D.

*/

public class Degrее { ... }

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

129

глагольную конструкцию (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саре - последовательностями.

131