Как написать хорошие комментарии javadoc?

Я разработчик Java, и я заинтересован в улучшении качества своих комментариев Javadoc в коде и программах, которые я пишу, чтобы сделать его более понятным и простым для других разработчиков.

Я читал много статей, в том числе из официальных источников, и я стараюсь следовать рекомендациям, изложенным в книге "Элементы стиля Java" , но, несмотря на это, и после многократного поиска в Интернете, я не могу найти практический способ сравнить мои существующие Javadoc (ы), чтобы моделировать примеры и поддерживать лучшие практики для документации Java API.

Ответ 1

Экспертная оценка.

Попробуйте найти кого-то вне вашей команды (клиента) и спросите их, что они думают о вашем JavaDoc.

Клиент всегда прав.

Также я могу поделиться с вами некоторыми вещами ниже

Отличное чтение о написании javadoc находится на сайте sun at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Лучшее, что я узнал из этого текста, вероятно, что ваш уровень javadoc на уровне класса должен начинаться с "Обеспечивает". Это заставляет вас думать о том, что этот класс предоставляет вашей программе (или миру). Это не редкость для меня, чтобы перепроектировать программное обеспечение, потому что написание javadoc заставило меня подумать "эй, это здесь не нужно!".

Другие практические советы: когда интересен интерес, попробуйте записать его в теге @returns. Не делать этого может означать, что вы вводите материал дважды, один раз в javadoc и один раз после тега @return.

Лучший совет: если вы не знаете, что писать, DONT. парсер Javadoc делает отличную работу по автоматическому генерации getter javadoc, например, но это происходит только тогда, когда вы не добавляли /** */.

Javadoc должен описать, ЧТО ваш метод делает, а не КАК.

Джавадок не твой тодолист. Я пробовал, но для больших проектов это просто не работает.

Ответ 2

В дополнение к документации Sun (теперь Oracle) на http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html Я бы рекомендовал " Пункт 44: Записать документы для всех открытых элементов API" из книги "Эффективная Java" Джошуа Блоха, 2-е изд. pp.203-208. Это рекомендация/рекомендации на 6 страниц с несколькими практическими примерами.

Ответ 3

Лучше всего, если вы опубликуете примерный метод, который вы написали, тогда мы можем помочь вам написать Javadoc для этого. Если вы просто просите общие предложения, то может быть трудно превзойти книгу.

Ответ 4

Вы можете использовать параметр @link для 'VoucherStore'

Пример:

@return {@link VoucherStore} type Concrete Object based on storeType parameter

вместо

 @return returns VoucherStore type Concrete Object based on storeType parameter.