メソッド/クラスのコメントは一貫して適用する必要がありますか、それとも必要ベースでのみ適用する必要がありますか？

Question

一貫性のために、たとえシンプルなゲッターとセッターの方法、または非常に小さなラッパークラスであっても、すべての方法とクラスにコメント（Javadocの形で）を常に適用しました。しかし、私はまた、コメントを不必要にすることが多い自己文書コードを書くよう努めています。つまり、必要な場合にのみコメントを書きます（それを行う前に、コメントをまったく必要としないようにコードを書き換えてみてください）。したがって、これらの2つのアプローチは互いに矛盾しているように見えます。

したがって、メソッドまたはクラスを一貫した方法で適用するコメントは、そのようなコメントを定義から完全に明確でない場合にのみ書くべきですか？

Answer 1

簡単なLitmusテストは、クラスにコードよりも多くのコメントがあるかどうかを確認することです。最近の場合、それはあなたのコードが複雑すぎて、誰にとっても使用しにくいことを意味します。

したがって、自明コードを書くことが最善です。また、セッターやゲッターのような明らかなものについてコメントを書く必要はありません。

だから私は一緒に行きます そのようなコメントは、意味が定義から完全に明確ではない場合にのみ書かれます。

Answer 2

私はすべてのメソッドのコードを作成していましたが、今ではコード自体よりも多くの情報を備えた場合にのみドキュメントを作成します。

がここにあります 質問 多くの答えがある同様のトピックについて。コードが進化するにつれて、ドキュメントの更新が「忘れられた」可能性があります。リンクの質問を参照すると、悪いドキュメントはドキュメントがまったくないよりも悪いです。