Мои Конспекты
Главная | Обратная связь

...

Автомобили
Астрономия
Биология
География
Дом и сад
Другие языки
Другое
Информатика
История
Культура
Литература
Логика
Математика
Медицина
Металлургия
Механика
Образование
Охрана труда
Педагогика
Политика
Право
Психология
Религия
Риторика
Социология
Спорт
Строительство
Технология
Туризм
Физика
Философия
Финансы
Химия
Черчение
Экология
Экономика
Электроника

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

 

 

быть истинными для того, чтобы клиент мог вызвать этот метод, и постусловия (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, хотя это не является общепринятым. Чаще

 

 

 

всего применяются следующие теги: <р> для разделения параграфов, <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, состоящих из множества взаимосвязанных

 

 

 

 

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

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

 

 

 

Глава 7

Доверь свою работу ✍️ кандидату наук!
Поможем с курсовой, контрольной, дипломной, рефератом, отчетом по практике, научно-исследовательской и любой другой работой



Поиск по сайту:







©2015-2020 mykonspekts.ru Все права принадлежат авторам размещенных материалов.