Используете ли вы Javadoc для каждого метода, который вы пишете?

47

@Claudiu

Когда я пишу код, который другие будут использовать - Да. Каждый метод, который может использовать кто-то другой (любой общедоступный метод), должен иметь javadoc, по крайней мере, указывая на его очевидную цель.

@Daniel Spiewak

Я тщательно документировать каждый публичный метод в каждом классе API. Классы, которые имеют публичные элементы, но не предназначенные для внешнего потребления, заметно выделяются в классе javadoc. Я также документирую каждый защищенный метод в каждом классе API, хотя и в меньшей степени. Это говорит о том, что любой разработчик, который расширяет класс API, уже будет иметь справедливое представление о том, что происходит.

И, наконец, я буду иногда документировать приватные и приватные частные методы для моей собственной выгоды. Любой метод или поле, которое, как мне кажется, нуждается в некотором объяснении в его использовании, получит документацию, независимо от ее видимости.

@Paul де Vrieze

Для вещей, как тривиальные добытчиками и сеттеров, делиться комментарий между тогда и описать назначение имущества, не геттера/сеттера

/** 
* Get the current value of the foo property. 
* The foo property controls the initial guess used by the bla algorithm in 
* {@link #bla} 
* @return The initial guess used by {@link #bla} 
*/ 
int getFoo() { 
    return foo; 
}

И да, это больше работы.

@VonC

При разрыве огромный комплексный метод (из-за high cyclomatic complexity причины) в:

один публичный метод вызова
несколько частных методов, которые представляют собой внутренние этапы общественного одного

, очень полезно также использовать частные методы, даже если эта документация не будет видна в файлы API javadoc.
Тем не менее, это позволяет вам легче запомнить точный характер различных шагов вашего сложного алгоритма.

И помните: limit values or boundary conditions также должен быть частью вашего javadoc.

Plus, Javadoc это лучше, чем просто «// комментарий»:

Признан IDE и используется для отображения всплывающего окна при наведении курсора на вершине одного вашей - javadoc-ed - функции. Например, константа - это частная статическая конечная переменная - должна иметь javadoc, особенно когда ее значение не является тривиальным. Дело в точке: регулярное_выражение (его Javadoc должна включает в себя регулярное выражение в его не-избежали формы, что является целью является и буквальным пример сопровождаться регулярным выражением)
Это может быть проанализировано с помощью внешних средств (например, xdoclet)

@Domci

Для меня, если кто-то увидит его или нет, не имеет значения, - это вряд ли я буду знать, что делает какой-то неясной кусок кода, который я написал после того, как пару месяцев , [...]
Короче говоря, логика комментариев, а не синтаксис, и делайте это только один раз, в нужном месте.

@Miguel Ping

Для того, чтобы прокомментировать что-то, вы должны понимать его первым. Когда вы пытаетесь прокомментировать функцию, вы на самом деле думаете о том, что делает метод/функция/класс, и это делает вас более конкретным и ясным в вашем javadoc, что, в свою очередь, заставляет вас писать более четкий и сжатый код, что хорошо ,

Используете ли вы Javadoc для каждого метода, который вы пишете?

ответ

Смежные вопросы