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

КОТ МАЛЫШ и его СЕКРЕТ ! КОШЕЧКА МУРЗЯ родила котенка Дайте ИМЯ милашке ! ПРИВЕТ ОТ КРОЛИКА БАФФИ


Читать еще…

Понравилась статья? Поделиться с друзьями: