api - APIのすべてのパブリックメソッドを文書化する必要がありますか？

Question

「ライブラリ」タイプのクラスを作成する場合、常にマークアップドキュメント（つまりjavadoc）をJavaで作成するか、コードを「自己ドキュメント化」できると想定する方がよいでしょうか。たとえば、次のメソッドスタブがあるとします。

/**
 * Copies all readable bytes from the provided input stream to the provided output
 * stream.  The output stream will be flushed, but neither stream will be closed.
 *
 * @param inStream an InputStream from which to read bytes.
 * @param outStream an OutputStream to which to copy the read bytes.
 * @throws IOException if there are any errors reading or writing.
 */
public void copyStream(InputStream inStream, OutputStream outStream) throws IOException {
    // copy the stream
}

javadocは自明のようであり、機能がまったく変更された場合に更新する必要があるノイズです。しかし、ストリームをフラッシュして閉じないことについての文章は価値があるかもしれません。

したがって、ライブラリを作成するときは、次のことを行うのが最適です。

a）常に文書化する
b）明白でないものはすべて文書化する
c）文書化しない（コードはそれ自体を語る必要がある！）

私は通常b）を使用します（コードは他の方法で自己文書化できるため）...

score 18 · Accepted Answer

a）常に文書化します。

これにより、自動化されたツールを使用して、Webベース、紙ベースなどのドキュメントを生成できます。これは、常にソースコードが前にあるとは限らないユーザーにとって非常に貴重な場合があります。

score 3 · Accepted Answer

これは、上司に頼まれたときだけ文書化するという「子供の頃は双方向の上り坂」というマントラをよく唱えていたところですが...最近、調子を変えました。オープンソースプロジェクト、一般的に呼び出されるライブラリに取り組んでいる場合、または他の誰かがあなたが提供しているインターフェイスと緊密に連携する必要があることを前もって知っている場合は、すべてのパブリックメソッドの完全なドキュメントを提供することが重要だと思います。 .

ドキュメンテーションは保守しやすいコードを作成しますが、やり過ぎて、機能の追加や単体テストに合格する作業を行う必要があるときに、コメントや POD や wiki を書くのに時間を費やしてしまう可能性があります。これは、アジャイルマニフェストで取り上げられています(つまり、対面式のコミュニケーションはドキュメントよりも優れているなど、インターフェイスメソッドのはしごを上っています)。

score 3 · Accepted Answer

特に API の場合、すべてのパブリックメソッド (およびフィールド) を実際に文書化する必要があります。さらに、メソッドのドキュメントは、利用可能な情報があいまいさの余地を残さないように、十分に明確で有益である必要があります。

API の良い例はJava API 仕様です。ドキュメントのタイトルから、仕様であることに注意してください。ドキュメントは、仕様と見なすのに十分なほど完全でなければならないと私は信じています。

ほとんどの場合、Java API 仕様は優れた例だと思いますが、十分に文書化されていない、または有益ではないことに気付いた部分がいくつかあります。DropTargetクラスを例にとってみましょう。というclearAutoscroll()メソッドがあり、そのメソッドの javadoc は次のとおりです。

clearAutoscroll

protected void clearAutoscroll()
clear autoscrolling

このような有益でない API のドキュメントほどイライラするものはありません。最悪の場合、提供される情報は 1 文にもなりません。すべてのパブリックフィールドとメソッドに提供されるドキュメントは、ライブラリのユーザーが通知されるのではなくイライラすることのないように、十分な情報を提供するものであることを確認してください。

score 2 · Accepted Answer

a)

他の人が述べたように、ドキュメントを生成でき、メンテナンスに役立ちます。

また、インテリセンスは、メソッド/プロパティが何をするか/何であるかを伝えることから恩恵を受けます。

score 2 · Accepted Answer

したがって、他の人が使用する API を開発している場合は、すべてのメソッド、プロパティなどの意図を明確にする必要があるというのが私の意見です。

メソッドを見て、次のことを知ることができるはずです。

それが返すもの、もしあれば、そしてその戻り値が特定の単位（フィート、メートル、度など）である場合、それは明確でなければなりません。ユーザーは、メソッドが摂氏、華氏、ケルビンのいずれを返すかを推測する必要があります。
必要なパラメータとその単位 (ある場合)
メソッドの目的と、それらのパラメーターと戻り値の範囲 (意味がある場合)
その他、読者に明らかでないもの

多くの API のユーザーとして、私は良いもの、悪いもの、醜いものを見てきました。多くのライターとして、特に数年前に書いたライブラリを使用する必要があり、コードを掘り下げて正確に判断する必要がある場合、インターフェイスを提供するときに明確で具体的でないことについて早い段階で教訓を学びました。書きながら考えていました。

私はあなたがドキュメンテーションに行き過ぎて、よく選ばれたメソッド、引数名などは読みやすさに大いに役立つと考える必要はないと思います。しかし、メソッドを記述している場合、それを文書化するのにかかる時間はわずか数秒 (おそらく 1 分程度) です。公開インターフェースを明確にし、必要な場所に文書化しないという説得力のある理由はありません。おそらくそれが「使い捨て」ライブラリである場合....しかし、私はそれらの多くを書きません。

ちょうど私の2セント。

score 1 · Accepted Answer

鈍感な人があなたのコードをレビューしたり変更したりしているとき、たとえドキュメントがなくても、それは完全に明確だと思うので、解釈のために何も残されていません。

score 1 · Accepted Answer

メソッド、フィールド、定数、What-have-you など、公的にアクセス可能なものはすべて、ユーザーまたは開発者 (包括的またはところで) が何年も後にやって来て、すべてを手に入れることができるように文書化する必要があります。文書化されたオブジェクトを利用するために必要な情報。使用するための前提条件、目的、投げられたもの、および使用後の変更点を文書化します。

明確かつ具体的に説明し、当て推量を一切残さないでください。そうしたい場合は、プロジェクトに関係のない人に文書化する内容の宣言を見せて、何か足りないものがないか尋ねてください。メモを取り、彼らの懸念がカバーされていることを確認してください。

Tout le monde は、コードは十分なドキュメントであるべきだと言っていますが、それは神話です。誰もがコードを見ているわけではありませんし、あなたがそのコードでどのような巧妙なトリックを行っているかを認識しているわけでもありません。したがって、他の人が見る可能性のあるものはすべて文書化してください。あなたのユーザー、仲間の開発者、そしてあなた自身が数年後に感謝するでしょう.

score 1 · Accepted Answer

私が a を選択したのは、純粋に、クラスを調査するときに、文書化されたパブリックメソッド (javadoc など) を見たいからです。それはいくつかのことを少し明確にします。しかし、それぞれ独自のものです。

score 1 · Accepted Answer

a)

メソッドの場合、ストリームのフラッシュとクローズに関して提供したものなど、常に重要な詳細がいくつかあります。たとえば、メソッド "String getFileExtension(String filename)" はドキュメントを必要としないように見えますが、"filename" に拡張子がない場合はどうなるでしょうか? その答えは文書化する必要があります。

それがタイプの場合、それが協力する他のタイプと、それがどのようにそれを行うかについて言及する必要があります。これにより、ユーザーは目的の方法でドキュメントをナビゲートすることができ、指示なしにドキュメントを参照するだけでは済みません。

score 1 · Accepted Answer

a)

事前に完全な文書化を行うことのもう 1 つの利点は、時間の経過に伴うメソッドの動作の変更を防ぐのに役立つことです。例では、ストリームをフラッシュして閉じないことについての文を引用しています。このレベルの詳細は、メソッドのユーザーが知る必要がある重要なセマンティクスです。これが文書化されていない場合、API のその後の実装でフラッシュが実行されず、メソッドのユーザーに予期しない結果が生じる可能性があります。

score 0 · Accepted Answer

常にドキュメント。

あなたにとって明白なことは、他の人にとっては明白ではないかもしれません。特に、彼らが別の視点から状況を見ている場合 (非コーダー、初心者、あなたの言語構造に慣れていないユーザー)

ドキュメントの完全性のためにも。

score 0 · Accepted Answer

b) 明らかでないこと、または疑わしいことはすべて文書化します。この場合：

/** Copies all readable bytes from inStream to outStream. outStream will be flushed, 
 *  but neither stream will be closed.
 */

inStream が InputStream であることは既に書いています。関数のコメントで既に行っているように、独自のコメントでバイトを読み取ることを意図していることを指定する必要はありません。

score 0 · Accepted Answer

人々に使用して効果的に使用してもらいたい方法だけを文書化してください。

score 0 · Accepted Answer

0

すべてのパブリックメソッドは文書化する必要があります。

于 2008-09-25T02:15:19.317 に答える

score 0 · Accepted Answer

オウムには申し訳ありませんが、常に文書化してください。

プライベートな機能であっても、常に文書化してください。知っていることを何度も忘れてしまいました。しかし、最初はすべてにコメントしたので、少なくともそれは簡単に理解できました。私がいくつかの小さなライブラリを作成したとき、私が作成したメモの一部がなければ、私が所属していたチームのすべての機能を文書化したので、内部の仕組みを解読することは完全に不可能でした.

私は途方もなく複雑なコードを書いたので、チームメイトの誰も理解できませんでした。ずさんな、または洗練されていないとは誰も考えませんでしたが、詳細な説明 (数時間かかる) の前に、誰もその論理に従うことができませんでした。一度紙に書いた後、それは私には明らかな答えのように思えましたが、これについては私の論理は他の人には異質でした.

そこで私は紙をスキャンし、すべての機能を文書化し、必要なすべての入力フォーマットをレイアウトし、アプリケーションがそのタスクをどのように達成するかについて追加の文書を書きました。私はその仕事を 3 年以上辞めましたが、今でも特定のことが必要になったときにそのソフトウェアについて話します (最近では 6 か月前)。それは Kloc (コードの 1000 行) 未満でしたが、それでも 2 年半後に疑問が生じるほど洗練されていました。

api - APIのすべてのパブリックメソッドを文書化する必要がありますか？

15 に答える 15

Related

Reference