メソッドが明らかに自明である場合、javadocコメントをスキップできます。
のようなコメント
/ ** Does Foo */ void doFoo（）;
本当に便利ではありません。 （非常に単純な例ですが、アイデアは得られます）
I 完全すべてのAPIクラスのすべてのパブリックメソッドを文書化します。パブリックメンバはあるが、外部消費を目的としていないクラスは、クラスjavadocで顕著にマークされています。それほどではありませんが、すべてのAPIクラスのすべての保護されたメソッドも文書化します。これは、APIクラスを拡張している開発者は何が起こっているのかという公正な概念をすでに持っているという考えに基づいています。
最後に、私自身のためにプライベートメソッドをパッケージ化し、プライベートメソッドをパッケージ化することがあります。可視性に関係なく、その使用法に何らかの説明が必要だと思われるメソッドまたはフィールドは、ドキュメントを受け取ります。
ささいなゲッターやセッターなど、その間でコメントを共有し、ゲッター/セッターではなくプロパティの目的を説明します。
/**
* Get foo
* @return The value of the foo property
*/
int getFoo() {
return foo;
}
役に立たない。次のようなことをしてください：
/**
* Get the current value of the foo property.
* The foo property controls the initial guess used by the bla algorithm in
* {@link #bla}
* @return The initial guess used by {@link #bla}
*/
int getFoo() {
return foo;
}
そして、はい、これはより多くの作業です。
すでに他の人がカバーしているすべての拠点。追加の注意事項：
あなたがこれをしていることに気付いた場合：
/**
* This method currently launches the blaardh into the bleeyrg.
*/
void execute() { ... }
これに変更することを検討してください：
void launchBlaardhIntoBleeyrg() { ... }
これは少し明白に思えるかもしれませんが、多くの場合、あなた自身のコードで機会を逃すのは簡単です。
最後に、変更はalwaysが必要ではないことに注意してください。たとえば、メソッドの動作は時間とともに変化することが予想されます（JavaDocの「現在」という言葉に注意してください）。
いいえ、すべてのメソッド、変数、クラスなどにコメントしないでください。
「Clean Code：A Handbook of Agile Software Craftsmanship」からの引用です：
すべての関数にjavadocが必要であるか、すべての変数にコメントが必要であると言うルールがあるのは、ばかげています。このようなコメントは、コードを混乱させ、嘘をつき、一般的な混乱と混乱を招きます。
メソッド、変数、クラスなどのintendedユーザーに重要な情報を追加する場合にのみ、コメントが存在する必要があります。私がこのメソッド/クラス/などに戻った場合、メソッドの結果/副作用、物が存在する理由の動機（いくつかのコードがいくつかのライブラリまたはシステムの欠点/バグを克服している場合） ）、パフォーマンスに関する重要な情報、またはいつ電話するのが適切かなど。
notは良いコメントですが、コード自体を書き換え/変更する必要があることを示すものは、複雑で曖昧なメソッドまたは関数の詳細を説明するコメントです。代わりに、より短く明確なコードを好む。
Javadocsを使用する必要がある別の理由があります。何かをコメントするには、まずそれを理解する必要があります。関数にコメントしようとすると、実際には思考メソッド/関数/クラスが何をするのか、そしてこれによりjavadocでより具体的かつ明確になり、より明確に書くことができます簡潔なコードは良いことです。
自分でコードを書くとき- 番号。この場合、Java doccingは私の時間の無駄です。
他の人が使用するコードを書くとき- はい。他の誰かが使用できるすべてのメソッド（任意のパブリックメソッド）には、少なくともその明白な目的を示すJava docが必要です。良いテストのために、コードでjavadoc作成ユーティリティを実行します（正確なコマンドライン）。生成されたWebページを参照します。そのレベルのドキュメントを備えたライブラリを使用して満足できる場合は、最高です。 コードにさらにjavadocを書く。
私にとっては、誰かがそれを見るかどうかは問題ではありません-数か月後に私が書いたコードの不明瞭な部分が何をするかを知ることはないでしょう。いくつかのガイドラインがあります：
API、フレームワーククラス、および内部で再利用可能な静的メソッドは、徹底的にコメントする必要があります。
複雑なコードの各部分のロジックは、2つの場所で説明する必要があります。javadocの一般的なロジックと、独自のコメント内のコードの意味のある各部分のロジックです。
モデルプロパティが明確でない場合はコメントする必要があります。たとえば、ユーザー名とパスワードをコメントする意味はありませんが、タイプには少なくともタイプの可能な値を示すコメントが必要です。
私はゲッター、セッター、または「本によって」行われたものを文書化しません。チームがフォーム、アダプター、コントローラー、ファサードを作成する標準的な方法を持っている場合、すべてのアダプターが同じで標準メソッドのセットを持っている場合は意味がないので、それらを文書化しません。フレームワークに精通している人なら誰でもその目的を知っているでしょう-フレームワークの哲学とそれを扱う方法がどこかに文書化されていると仮定して。この場合、コメントは余分な混乱を意味し、目的はありません。クラスが非標準的なことを行う場合、これには例外があります-短いコメントが便利です。また、標準的な方法でフォームを作成している場合でも、フォームの一部を短いコメントで分割して、コードを複数の部分に分割します（たとえば、「請求先はここから始まります」）。
つまり、構文ではなくロジックをコメントし、適切な場所で一度だけ実行します。
Java docは、コードだけでなくJava docを維持するために変更を行う開発者に負担をかけるため、依存しないでください。
クラス名と関数名は、何が起こっているかを説明するのに十分なほど明確でなければなりません。
クラスまたはメソッドが何をするのかを説明するために名前が長すぎて対処できない場合、クラスまたはメソッドは十分に焦点を合わせていないため、小さな単位にリファクタリングする必要があります。
少なくとも、受け入れられるパラメーターに関するコメントと、返されるタイプについてのコメントが必要だと感じています。
たとえば、sendEmail（..）;など、関数名で完全に記述されている場合は、実装の詳細をスキップできます。
Javadocは、ライブラリおよび再利用可能なコンポーネントに非常に役立ちます。しかし、もっと実用的にしましょう。 javadocよりも自己説明的なコードが重要です。 Javadocsを使用した巨大なレガシープロジェクトを想像するなら、それに頼りますか？私はそうは思いません...誰かがJavadocを追加した後、実装が変更され、新しい機能が追加（削除）されたため、Javadocは廃止されました。先ほど述べたように、ライブラリにはjavadocsが必要ですが、アクティブなプロジェクトには
- 何をするかを説明する名前を持つ小さな関数/クラス
- 関数/クラスが何をするのかを説明するユニットテストケースをクリアする
おそらく、すべてのメソッドを実際に文書化する必要があります。最も重要なのは、パブリックAPIメソッド（特に公開されているAPIメソッド）です。プライベートメソッドはドキュメント化されていない場合がありますが、明確にするためだけにすべきであると思いますが、保護されたメソッドについても同様です。コメントは有益なものであり、コードが何をするのかを繰り返したものではありません。
メソッドが特に複雑な場合は、文書化することをお勧めします。コメントを必要としないように、コードを明確に記述する必要があると考える人もいます。ただし、これは常に可能とは限らないため、これらの場合はコメントを使用する必要があります。
コードテンプレートを使用して、Eclipseからgetter/setterのJavadocコメントの生成を自動化して、記述する必要のあるドキュメントの量を節約できます。もう1つのヒントは、@ {$ inheritDoc}を使用して、インターフェイスと実装クラス間のコードコメントの重複を防ぐことです。
簡単に言えば：はい
あなたがドキュメントを書くべきかどうかを考える必要がある時間は、ドキュメントを書くことにもっと投資されます。
ワンライナーを書く方が、メソッドをまったくドキュメント化しないために時間を費やすよりも優れています。
これまでのすべての回答で想定されているのは、コメントが良いコメントになるということです。常にそうであるとは限らないことは誰もが知っているように、時には間違っていることさえあります。その意図、境界、および予想されるエラー動作を判断するためにコードを読む必要がある場合、コメントはありません。たとえば、メソッドはスレッドセーフで、引数はnullでも、nullを返すこともできます。コメントはコードレビューの一部である必要があります。
コードベースのメンテナーは、APIユーザーにはない問題に対処する必要があるため、これはプライベートメソッドにとってさらに重要な場合があります。
おそらくIDEには、開発者が現在のメソッドに重要で適用可能なさまざまなプロパティをチェックできるように、ドキュメント化フォームを使用できる機能が必要です。
Javadocコメントを持たないコードに対してjavadocを実行できます。メソッドとパラメーターに思慮深い名前を付けると、かなり有用なjavadocが生成されます。
自明ではないときはいつでもjavadocコメントを書くことが重要です。EclipseやnetbeansのようなIDEを使用するときにjavadocコメントを書くことはそれほど面倒ではありません。それに、javadocコメントを書くとき、メソッドが何をするのかだけでなく、メソッドが何をするのかexactly、そしてあなたが行った仮定について考えることを余儀なくされています。
もう1つの理由は、コードを理解してリファクタリングすると、javadocではいつでも参照できるため、コードの動作を忘れることができるためです。私はあなたのメソッドが何をするのかを意図的に忘れることを主張しているわけではありませんが、より重要な他のことを覚えておきたいということです。
少なくとも、すべてのパブリックおよびインターフェイスのプロパティとメソッドを文書化することで、コードを呼び出している人が何かを理解できるようにします。また、メンテナンスのために、できる限りコメントするようにしています。私自身のためだけに自分の時間で行う「個人的な」プロジェクトでさえ、Javadocを1年間保管し、後で戻ってくる可能性があるためです。