web-dev-qa-db-ja.com

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

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

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

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

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

8
Todd Davies

実装ではなく、インターフェースへのプログラミングが推奨されるでしょう。

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

APIを使用しているときは、抽象化に反対しています。 what APIが提供する(契約)だけを考慮し、how(実装)は考慮しないでください。

これは、たとえ契約が変更されていなくても、APIの実装がバージョン間で大幅に変更されないという保証がないためです。

23
MetaFight

インターフェースと実装の違いを除いて、 (前の回答ですでに説明されています 、別の重要な側面があります:complexity

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

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

実験できます。

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

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

4

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

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

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

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

0
Telastyn