最近、私が現在扱っているコードベースの部分のリファクタリングに取り組んでいます-自分自身をよりよく理解するためだけでなく、コードに取り組んでいる他の人にとってそれをより簡単にするために。
私は、自己文書化コードは素晴らしいと考える側に傾く傾向があります。私はちょうどそれがきれいだと思うし、コードがそれ自体のために話すなら、まあ... それは素晴らしいです。
一方、javadocsなどのドキュメントがあります。私もこれが好きですが、ここのコメントが時代遅れになるという特定のリスクがあります（もちろん一般的なコメントも同様です）。ただし、それらが最新の場合、複雑なアルゴリズムを理解するなど、非常に役立ちます。
これのベストプラクティスは何ですか？自己文書化コードとjavadocsの間のどこに線を引きますか？
回答:
自己文書化コード（およびコード内コメント）とJavadocコメントには、2つの非常に異なる対象読者がいます。
コードファイルに残っているコードとコメントは、開発者向けです。ここで彼らの懸念に対処したい-コードが何をするのか、なぜコードがそうであるのかを理解しやすくする。適切な変数名、メソッド、クラスなど（自己文書化コード）をコメントと組み合わせて使用すると、これが実現します。
Javadocコメントは通常、APIのユーザー向けです。これらは開発者でもありますが、システムの内部構造は気にしません。システムのクラス、メソッド、入力、および出力だけを気にします。コードはブラックボックス内に含まれています。これらのコメントを使用して、特定のタスクの実行方法、操作の予想される結果、例外がスローされるタイミング、および入力値の意味を説明する必要があります。Javadocによって生成された一連のドキュメントを考えると、コードの行を見ることなく、インターフェイスの使用方法を完全に理解できるはずです。
コードはその方法を示しています。コメントは理由を言っていて、たぶんそうではないのです。
コードの将来の読者とメンテナーの両方に提供するのはあなたの仕事です。できる限りコードに入れ、残りをコメントに入れます。
キャプチャするのが最も難しいものは設計上の決定であることに注意してください-それらも覚えておいてください。
Javadocsを使用しても実質的な違いはありません-生成されたドキュメントには関数の名前とコメントのテキストが含まれているため、関数名自体から明らかなコメントで何かを繰り返す必要はまったくありません。
一方、実装を見て最初に目的を理解する必要がある（したがって、この情報をJavadocsで利用できないようにする）関数がある場合、コードは自己文書化ではなくIMHOです実装がどれほど明確か。
javadocsの場合、物事は他のドキュメントの場合とまったく同じだと思います。主なルールは次のとおりです。
でください多くの人々があなたのjavadocを読んで？はいの場合、それを正しくするための努力を投資することは理にかなっています。
あなたの読者は、javadocを勉強するためにコードの読み取りをスキップする傾向がありますか？もしそうなら、それをうまく書くために努力を費やすことは2倍の意味をなします。
さて、あなたの場合ですか？そうでない場合は、javadocsに投資した努力が正当化されるかどうかをもう一度考えてください。
すでに上で指摘したように、聴衆の意見を聞いて道を見つけます。
Javadocコメントが古くなる可能性があるという懸念についてコメントしたいだけです。@JonathanMerletはJavadocを安定させるべきだと言っていますが、ピアレビュー中にJavadocとコメント、コードを確認することもできます。コメントはコードの実行内容と一致していますか？そうでない場合、これは間違っており、開発者に修正を要求します。他の開発者にも同じことをするように奨励してください。これにより、外部ドキュメント（Javadocコメント）だけでなく、通常のコードコメントも最新の状態に保つことができます。これにより、リファクタリング後に登場する開発者がコードをより迅速かつ簡単に理解できるようになり、将来のメンテナンスがより簡単になります。
安定性を保つ必要がある部分（API）にはjavadocが適切であるため、コメントが古くなるリスクを最小限に抑えることができますが、頻繁に変更（実装）される場合には自己文書化コードが最適です。もちろん、APIはプロジェクトの進行中に変更される可能性がありますが、宣言の直前にヘッダーを持ち、両方を同期させることはそれほど難しくありません（複数行のコードを説明する複数行のコメントと比較して）