ライブラリに慣れるために、ソースコードを読むよりもjavadocを読む方が望ましいですか。

私は大学の研究室のマニュアルで以下に出くわしました：

javadocを生成してクラスのインターフェースを調べる必要があるので、提供される操作を確認できます（コードを自由に見てください。ただし、他の誰かのコードを使用する場合は、ここでは、javadocではなくjavadocから作業する必要があります）可能な限りコード）。

なぜそうなのか理解できません。javadocが古くなっている可能性があるか、コードの機能を不適切に説明している可能性があるためです。確かにソースコードを見て、javadocコメントを読むのが最善でしょうか？

javadocのみを読むことが最善の方法である理由、またはその理由はありますか？

推奨事項は、実装ではなくインターフェイスへのプログラミングに関するものです。

確かに、コードにアクセスできる場合は、実装を調べてどのように機能するかを理解するのを妨げるものは何もありません。ただし、方法がAPIの消費に影響しないことを常に確認する必要があります。

APIを使用しているときは、抽象化に反対しています。APIが提供するもの（契約）だけに関心を持ち、方法（実装）に関心を向けないようにしてください。

これは、コントラクトが変更されていない場合でも、APIの実装がバージョン間で大幅に変更されないという保証がないためです。

インターフェースと実装の違いは別として、前の回答ですでに説明しましたが、もう1つの重要な側面があります。それは複雑さです。

通常、実際のシステムは複雑です。クラスのコードを読み始めると、別のクラスのコードを読み、次に別のクラスのコードを読む必要があることにも気づくでしょう。数時間後、単純にすべての複雑さと、誰が何を、どのような場合に呼び出すのか覚えていません。

インターフェースのコメントのみを使用すると、この複雑さを軽減できます。裏側では、すべてが簡単なのかもしれません。または、内部では、数十または数百のクラスが相互に作用して、イメージ全体を頭の中に保持することが実質的に不可能になっている可能性があります。

実験できます。

• OpenCVで興味のある部分を見つけてください。インターフェイスのドキュメントを読みます。基本を理解してライブラリを効果的に使用できるようになるまでにはどのくらい時間がかかりますか？

• 次に、実装を確認します。インターフェイスから直接呼び出されるクラスの数はいくつですか？これらのクラスのそれぞれからいくつのクラスが呼び出されますか？コードは何行ありますか？メソッドはいくつありますか？脳でスタックオーバーフローが発生する前に、このすべてのソースコードを探索するのにどのくらい時間がかかりますか？

javadocのみを読むことが最善の方法である理由、またはその理由はありますか？

JavaDocが古くなっている、または不良である可能性があることは完全に正しいですが、IDEのコードよりもホールセールを読み取るための形式の方がよくなる傾向があります。さらに重要なことに、それは自然言語です。これは次の2つの場合に重要です。

1. コードを読むことに慣れていない人々。たとえば、大学生は、学習過程にあるコードを理解しようとするよりも、関数の自然言語の説明を読む方がより良い結果をもたらすことが多いでしょう。
2. 主要言語として英語（または少なくとも音声アルファベットを使用する言語）を使用しない人々。JavaDocは、識別子では使用できない文字を処理できるため、それらのユーザーに何が起こっているかをより適切に説明できます。特にJavaDocには、ドキュメントをローカライズする機能さえあるようです。

とはいえ、私は可読コードをかなり信じています。経験豊富な開発者にとって、コードを読むことは、そのオプションが利用可能であれば、ほとんどの場合、より良いアプローチになると期待しています。