自己文書化コードvs Javadocs？
最近、私は現在扱っているコードベースの一部のリファクタリングに取り組んでいます。自分自身を理解するだけでなく、コードに取り組んでいる他の人が簡単に理解できるようにするためでもあります。
自己文書化コードは素晴らしい であると考える側に寄りがちです。私はそれがよりクリーンだと思います、そしてコードがそれ自体を語るなら、まあ... それは素晴らしいです 。
一方、javadocsなどのドキュメントがあります。私もこれが好きですが、ここのコメント（もちろん、一般的なコメントも）が古くなるという特定のリスクがあります。ただし、それらが最新の場合、複雑なアルゴリズムを理解するなど、非常に役立つ場合があります。
これのベストプラクティスは何ですか？自己文書化コードとjavadocsの間にどこで線を引きますか？
自己文書化コード（およびコード内コメント）とJavadocコメントには、2つの非常に異なる対象読者があります。
コードファイルに残っているコードとコメントは開発者向けです。ここで彼らの懸念に対処したいと思います-コードが何をするのか、なぜコードが現状通りであるのかを理解しやすくします。適切な変数名、メソッド、クラスなど（自己文書化コード）をコメントと組み合わせて使用すると、これを実現できます。
Javadocコメントは通常、APIのユーザー向けです。これらも開発者ですが、システムの内部構造については気にせず、システムのクラス、メソッド、入力、および出力のみを気にします。コードはブラックボックス内に含まれています。これらのコメントは、特定のタスクの実行方法、予想される操作の結果、例外がスローされるタイミング、および入力値の意味を説明するために使用する必要があります。 Javadocで生成された一連のドキュメントがあれば、コードの行を見なくても、インターフェイスの使用方法を完全に理解できるはずです。
コードはhowと言っています。コメントはwhy、そしておそらくwhy notとさえ言います。
コードの将来の読者とメンテナーの両方に提供するのはあなたの仕事です。できる限りのことはコードに入れ、残りはコメントに入れてください。
キャプチャするのが最も難しいのは設計上の決定であることに注意してください-それらも忘れないでください。
Javadocsを使用しても、実際の違いはありません。生成されたドキュメントにはコメントのテキストと一緒に関数の名前が含まれているため、関数名自体から明らかなコメントで何かを繰り返す必要がある理由はまったくありません。
一方、実装を調べて何が良いかを理解する必要がある関数がある場合（したがって、この情報をJavadocで利用できるようにしない）、コードはIMHOであり、自己文書化されていません。実装がどれほど明確か。
Javadocsの場合、すべてのドキュメントとまったく同じだと思います。主なルールは次のとおりです。
聴衆をフォローする
多くの人があなたのjavadocを読んでいますか？もしそうなら、それを正しくするために努力を投資することは理にかなっています。
あなたの読者は、javadocの研究を支持して読み取りコードをスキップする傾向がありますか？もしそうなら、それをうまく書くことに努力を費やすことは2倍の意味があります。
- これは JDKドキュメント の場合とまったく同じです。 Sun/Oracleがこれらに多大な労力を費やしたと思います。彼らは、コミュニティで多く使用されているAPIドキュメントに素晴らしい見返りがあるようです。
さて、それはあなたのケースですか？そうでない場合は、javadocへの投資が正当化されるかどうかをよく検討してください。
すでに上で指摘したように、聴衆に耳を傾け、方法を見つけます。
- ドキュメントが不十分であるという激しい不満を聞いた場合は、ドキュメントの改善に投資することを検討してください。
一方、あなたが聞いたすべてが、無駄なタイピングに時間を浪費することを強いる頭の悪いルールについて愚痴を言う開発者である場合、Javadocの取り組みが subprime mortgagesに投資するようなものである可能性が高い 。代わりに、より良い投資を考えてください。
Javadocコメントが古くなるかもしれないという懸念についてコメントしたいと思います。 @JonathanMerletはJavadocは安定しているべきだと言っていますが、Javadocとコメント、およびピアレビュー中にコードを確認することもできます。コメントはコードが行っていることと一致していますか？そうでない場合、これは誤りであり、開発者に修正を要求します。他の開発者にも同じことをするように勧めてください。これにより、外部ドキュメント（Javadocコメント）だけでなく、通常のコードコメントも最新の状態に保つことができます。これは、リファクタリングの後にやってきた開発者がコードをより迅速かつ簡単に理解できるようにし、将来的にコードをずっと簡単に維持できるようにします。