Должен ли я документировать не требующие пояснений частные методы? (Джава)

Question

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

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

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

Каков стандартный подход к этому?

Answer 1

Да.

Если кто-нибудь когда-либо будет смотреть на ваш код, документируйте. Это стоит дополнительной строки или двух. Ваш код будет выглядеть более согласованным и понятным. Если кто-то еще когда-нибудь увидит ваш код, вы обязательно должны прокомментировать.

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

Answer 2

Я лично документирую все, что может вызвать неоднозначность позже. Я бы не документировал

def next = counter.incrementAndGet()

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

Кроме того, в частных методах я бы не беспокоился о соблюдении стандартов Javadoc. Просто написав несколько комментариев, вы попали в мои хорошие книги. Мне не нужны @param или @return. Это для публичных API.