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

Question

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

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

Answer 1

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

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

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

Answer 2

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

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