Должны ли комментарии метода / класса применяться последовательно или только по необходимости?

Question

Для согласованности я всегда применял комментарии (в форме JavaDoc) ко всем методам и классам, даже если они являются простыми методами получения и установки или очень маленькими классами-обертками. Но я также стремлюсь написать самодокументированный код, который часто делает комментарии излишними; т.е. писать комментарии только там, где это необходимо (и прежде чем делать это, попробуйте переписать код, чтобы он вообще не нуждался в комментариях). Следовательно, эти два подхода кажутся противоречащими друг другу.

Так должны ли комментарии, описывающие метод или класс, применяться последовательно или такие комментарии должны быть написаны только тогда, когда значение не совсем ясно из определения?

Answer 1

Раньше я создавал код для каждого метода, но теперь я создаю документацию только тогда, когда замечания добавляют больше информации, чем сам код.

Вот вопрос на похожую тему с множеством ответов.По мере развития кода существует вероятность того, что обновление документации будет «забыто».Ссылка на вопрос в ссылке плохая документация хуже, чем отсутствие документации вообще.

Answer 2

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

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

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