私は大学の研究室のマニュアルで以下に出くわしました:
Javadocを生成してクラスのインターフェースを調べる必要があるので、提供される操作を確認できます(コードを自由に見てください。ただし、他の誰かのコードを使用する場合は、ここでは、javadocではなくjavadocから作業する必要があります)可能な限りコード)。
なぜそうなのか理解できません。 javadocが古くなっている可能性があるか、コードの機能を不適切に説明している可能性があるためです。確かにソースコードを見て、javadocコメントを読むのが最善でしょうか?
Javadocのみを読むことが最善の方法である理由、またはその理由はありますか?
実装ではなく、インターフェースへのプログラミングが推奨されるでしょう。
確かに、コードにアクセスできる場合は、実装を見て理解するのを妨げるものは何もありませんhow機能します。ただし、常にhowがAPIの消費に影響を与えないようにする必要があります。
APIを使用しているときは、抽象化に反対しています。 what APIが提供する(契約)だけを考慮し、how(実装)は考慮しないでください。
これは、たとえ契約が変更されていなくても、APIの実装がバージョン間で大幅に変更されないという保証がないためです。
インターフェースと実装の違いを除いて、 (前の回答ですでに説明されています 、別の重要な側面があります:complexity 。
通常、実際のシステムは複雑です。クラスのコードを読み始めると、別のクラスのコードを読み、次に別のクラスのコードも読む必要があることがわかります。数時間後、単純にすべての複雑さと、誰が何を、どのような場合に呼び出すのか覚えていません。
インターフェースのコメントのみを使用すると、この複雑さを軽減できます。裏側では、すべてが簡単なのかもしれません。または、内部では、数十または数百のクラスが相互に作用して、イメージ全体を頭の中で維持することが実質的に不可能になっている可能性があります。
実験できます。
Javadocのみを読むことが最善の方法である理由、またはその理由はありますか?
JavaDocが古くなっている、または不良である可能性があることは完全に正しいですが、IDEのコードよりもホールセールを読み取るための形式の方がよくなる傾向があります。さらに重要なことに、それは自然言語です。これは次の2つの場合に重要です。
とはいえ、私は可読コードをかなり信じています。経験豊富な開発者にとって、コードを読むことは、そのオプションが利用可能であれば、ほとんどの場合、より良いアプローチになると期待しています。