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

Question

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

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

Answer 1

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

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

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

Answer 2

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

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