Javadoc @return комментарий дублирования необходимо?

Для функций, которые не изменяют состояние экземпляра, комментарий javadoc для метода часто тот же или очень похожий, что и для тега @return-tag в Java-API.

Теперь я пишу javadoc для многих простых методов, таких как getExpression(), где у меня такая же проблема. Должен ли я делать это как в API или оставить его?

Ответы

Ответ 1

Из рекомендации Oracle Как написать комментарии к Doc для Javadoc Tool:

@return (справочная страница)

Отключить @возврат для методов, возвращающих void и для конструкторов; включить его для всех других методов, даже если его содержимое полностью избыточным с описанием метода. Наличие явного тега @return позволяет кому-то быстро найти возвращаемое значение. Всякий раз, когда возможно, указать значения возврата для особых случаев (например, указать значение, возвращаемое при предоставлении аргумента вне пределов).

Ответ 2

Если вы (как и я) действительно не любите нарушать DRY, то это одна из самых важных строк javadoc ref:

Возможно иметь комментарий только с разделом тега и без основного описания.

(@см. http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#tagsection)

Таким образом, совершенно справедливо (и работает) для простых методов для написания вашего javadoc:

/**
* @return the name of the object
*/
public String getName();

Итак, вы могли бы написать что-то вроде этого:

/**
* @return the n-th element of the object
*
* @param n index of element to get
*/
public String get( int n );

Что (после небольшого познания друг друга) более читабельны в источнике и лучше поддерживаются как более длинная форма, которая нарушает DRY.