java - 作成するすべてのメソッドにJavadocを使用していますか？

Question

すべてのJavaメソッドのドキュメントコメントを書く必要がありますか？

score 55 · Accepted Answer

@Claudiu

他の人が使用するコードを書くとき-はい。他の誰かが使用できるすべてのメソッド（任意のパブリックメソッド）には、少なくともその明白な目的を示すjavadocが必要です。

@ダニエルシュピーワク

すべてのAPIクラスのすべてのパブリックメソッドを徹底的に文書化します。パブリックメンバーはあるが外部消費を目的としていないクラスは、クラスjavadocで目立つようにマークされています。また、程度は低いですが、すべてのAPIクラスのすべての保護されたメソッドを文書化します。これは、APIクラスを拡張している開発者は、何が起こっているのかについての公正な概念をすでに持っているという考えに基づいています。

最後に、私自身の利益のために、プライベートメソッドとパッケージプライベートメソッドをときどき文書化します。使用法について説明が必要だと思うメソッドやフィールドは、その可視性に関係なく、ドキュメントを受け取ります。

@Paul de Vrieze

些細なゲッターやセッターのようなものについては、その間のコメントを共有し、ゲッター/セッターではなく、プロパティの目的を説明してください

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

そして、はい、これはより多くの作業です。

@VonC

非常に複雑な方法（循環的複雑度が高いため）を次のように分解すると、次のようになります。

1つのパブリックメソッド呼び出し
パブリックメソッドの内部ステップを表すいくつかのプライベートメソッド

、そのドキュメントがjavadoc APIファイルに表示されない場合でも、プライベートメソッドをjavadocすることは非常に便利です。
それでも、複雑なアルゴリズムのさまざまなステップの正確な性質をより簡単に思い出すことができます。

また、制限値または境界条件もjavadocの一部である必要があることを忘れないでください。

さらに、javadocは単純な「//コメント」よりもはるかに優れています。

これはIDEによって認識され、カーソルを-javadoc-ed-関数の1つの上に移動したときにポップアップを表示するために使用されます。たとえば、定数（プライベート静的最終変数）には、特にその値が重要でない場合は、javadocが必要です。適切な例：regexp（そのjavadocには、エスケープされていない形式のregexpが含まれている必要があります。目的は何であり、文字通りの例はregexpと一致します）
外部ツール（ xdocletなど）で解析できます

@Domci

私にとって、誰かがそれを見るかどうかは関係ありません-私が書いたコードのいくつかのあいまいな部分が数ヶ月後に何をするかを私が知ることはないでしょう。[...]
要するに、構文ではなくロジックにコメントし、適切な場所で1回だけ実行します。

@ミゲルピン

コメントするには、まずそれを理解する必要があります。関数にコメントしようとすると、実際にはメソッド/関数/クラスが何をするかを考えていることになります。これにより、javadocでより具体的かつ明確になり、より明確で簡潔なコードを記述できるようになります。これは良いことです。。

score 32 · Accepted Answer

メソッドが明らかに自明である場合は、javadocコメントをスキップする可能性があります。

のようなコメント

/**Fooはしますか*/
 void doFoo（）;

本当に役に立たない。（非常に単純な例ですが、アイデアは得られます）

score 27 · Accepted Answer

すべてのAPIクラスのすべてのパブリックメソッドを徹底的に文書化します。パブリックメンバーはあるが外部消費を目的としていないクラスは、クラスjavadocで目立つようにマークされています。また、程度は低いですが、すべてのAPIクラスのすべての保護されたメソッドを文書化します。これは、APIクラスを拡張している開発者は、何が起こっているのかについての公正な概念をすでに持っているという考えに基づいています。

最後に、私自身の利益のために、プライベートメソッドとパッケージプライベートメソッドをときどき文書化します。使用法について説明が必要だと思うメソッドやフィールドは、その可視性に関係なく、ドキュメントを受け取ります。

score 15 · Accepted Answer

些細なゲッターやセッターのように、その間のコメントを共有し、ゲッター/セッターではなく、プロパティの目的を説明します。

/** 
 * Get foo
 * @return The value of the foo property
 */
int getFoo() {
  return foo;
}

役に立たない。次のようなことをお勧めします。

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

そして、はい、これはより多くの作業です。

score 15 · Accepted Answer

すべての基地はすでに他の基地でカバーされています。1 つの追加のメモ:

これを行っていることに気付いた場合：

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

これを次のように変更することを検討してください。

void launchBlaardhIntoBleeyrg() { ... }

これは少し明白に思えるかもしれませんが、多くの場合、独自のコードではこの機会を簡単に逃してしまいます。

最後に、変更が常に必要なわけではないことに注意してください。たとえば、メソッドの動作は時間の経過とともに進化すると予想される場合があります (JavaDoc の「現在」という単語に注意してください)。

score 10 · Accepted Answer

いいえ、すべてのメソッド、変数、クラスなどをコメントしないでください.

以下は「Clean Code: A Handbook of Agile Software Craftsmanship」からの引用です。

すべての関数に javadoc が必要である、またはすべての変数にコメントが必要であるというルールを設定するのは、まったくばかげています。このようなコメントは、コードを乱雑にし、嘘を広め、一般的な混乱と混乱を招くだけです。

コメントは、メソッド、変数、クラスなどの意図したユーザーにとって重要な情報を追加する場合にのみ存在する必要があります.「重要」を構成するものは検討に値し、いつ/戻ってきた場合に自分自身に思い出させることができます.このメソッド/クラス/などへの影響、メソッドの結果/副作用、それが存在する理由の動機 (一部のコードが一部のライブラリまたはシステムの欠点/バグを克服している場合)、パフォーマンスに関する重要な情報または、電話するのが適切な場合など。

良いコメントではありませんが、コード自体を書き直す/変更する必要があることを示すのは、複雑であいまいなメソッドまたは関数の詳細を説明するコメントです。代わりに、より短く、より明確なコードを優先してください。

score 6 · Accepted Answer

javadocs を使用する必要がある別の理由があります。何かをコメントするには、まずそれを理解する必要があります。関数にコメントを付けようとすると、実際にはメソッド/関数/クラスが何をするかを考えています。これにより、javadoc でより具体的かつ明確になり、より明確で簡潔なコードを記述できるようになります。これは良いことです。 .

score 6 · Accepted Answer

自分でコードを書くとき -いいえ。この場合、Java ドッキングは時間の無駄です。

他の人が使用するコードを書くとき -はい。他の誰かが使用できるすべてのメソッド (すべてのパブリックメソッド) には、少なくともその明白な目的を示す Java ドキュメントが必要です。適切なテストのために、コードで javadoc 作成ユーティリティを実行します (正確なコマンドラインは忘れてしまいました)。生成された Web ページを参照します。そのレベルのドキュメントを備えたライブラリを使用して満足するなら、あなたは金です。そうでない場合は、コードにさらに javadoc を記述してください。

score 2 · Accepted Answer

コードだけでなく Java ドキュメントを維持するために変更を加える開発者に負担がかかるため、Java ドキュメントに依存するべきではありません。

クラス名と関数名は、何が起こっているのかを十分に説明できるように明示する必要があります。

クラスまたはメソッドの機能を説明するためにその名前が長くなりすぎて対処できない場合、そのクラスまたはメソッドは十分に焦点を絞っていないため、より小さな単位にリファクタリングする必要があります。

score 2 · Accepted Answer

私にとっては、誰かがそれを見るかどうかは問題ではありません。私が書いたあいまいなコードが数か月後に何をするかを知ることはまずありません。いくつかのガイドラインがあります。

API、フレームワーククラス、および内部で再利用可能な静的メソッドは、完全にコメントする必要があります。
すべての複雑なコードのロジックは、2 つの場所で説明する必要があります。javadoc の一般的なロジックと、それ自体のコメントのコードの意味のある部分ごとのロジックです。
モデルのプロパティが明確でない場合は、コメントする必要があります。たとえば、ユーザー名とパスワードにコメントを付けても意味がありませんが、タイプには、タイプに可能な値を示すコメントが少なくとも必要です。
ゲッター、セッター、または「本によって」行われたことについては文書化しません。チームがフォーム、アダプター、コントローラー、ファサードを作成する標準的な方法を持っている場合...すべてのアダプターが同じで、一連の標準メソッドがある場合は意味がないため、それらを文書化しません。フレームワークに精通している人なら誰でも、フレームワークの哲学とそれを使用する方法がどこかに文書化されていると仮定して、それらが何のためにあるのかを知っています。この場合、コメントは余分な混乱を意味し、何の意味もありません。クラスが非標準的なことを行う場合、これには例外があります - その場合、短いコメントが役に立ちます。また、標準的な方法でフォームを作成している場合でも、「請求先住所はここから始まります」など、コードをいくつかの部分に分割する短いコメントでフォームの一部を分割するのが好きです。

要するに、構文ではなくロジックにコメントし、適切な場所で一度だけ実行します。

score 2 · Accepted Answer

簡単に言えば：はい

ドキュメントを書くべきかどうかを考えるのに必要な時間は、ドキュメントを書くことに投資したほうがよいでしょう。

最後にメソッドをまったく文書化しないために時間を費やすよりも、ワンライナーを作成する方がよいでしょう。

score 1 · Accepted Answer

おそらく、すべてのメソッドを実際に文書化する必要があります。最も重要なのは公開 API メソッド (特に公開 API メソッド) です。明確にするために、プライベートメソッドは文書化されていないことがありますが、文書化する必要があると思います-保護されたメソッドについても同様です。コメントは、コードが何をするかを繰り返すだけではなく、情報を提供するものでなければなりません。

メソッドが特に複雑な場合は、文書化することをお勧めします。コメントを必要としないように、コードを明確に記述する必要があると考える人もいます。ただし、これは常に可能であるとは限らないため、このような場合はコメントを使用する必要があります。

コードテンプレートを使用して Eclipse からの getter/setter の Javadoc コメントの生成を自動化して、作成するドキュメントの量を節約できます。もう 1 つのヒントは、@{$inheritDoc} を使用して、インターフェイスと実装クラスの間でコードコメントが重複しないようにすることです。

score 1 · Accepted Answer

受け入れられるパラメーターと戻り値の型について、それらが何であるかという観点から、少なくともコメントが必要だと思います。sendEmail(..)
のように、関数名が完全に説明している場合は、実装の詳細をスキップできます。

score 0 · Accepted Answer

自明でない場合はいつでも javadoc コメントを書くようにしています。Eclipse や netbeans のような IDE を使用しているときに javadoc コメントを書くことはそれほど面倒ではありません。その上、javadoc コメントを書くときは、メソッドが何をするかだけでなく、メソッドが正確に何をするか、およびあなたが行った仮定について考える必要があります。

もう 1 つの理由は、コードを理解してリファクタリングすると、javadoc をいつでも参照できるため、Javadoc が何をするかを忘れることができるからです。私はあなたのメソッドが何をするかを意図的に忘れることを主張しているわけではありませんが、より重要な他のことを覚えておくことを好むだけです.

score 0 · Accepted Answer

これまでのすべての回答で、コメントは良いコメントになると想定されています。常にそうであるとは限らないことは誰もが知っているように、時にはそれらが間違っていることさえあります. コードの意図、境界、予想されるエラー動作を判断するためにコードを読む必要がある場合は、コメントが不足しています。たとえば、メソッドはスレッドセーフか、任意の引数を null にできるか、null を返すことができるかなどです。コメントはコードレビューの一部にする必要があります。

これは、コードベースのメンテナーが API ユーザーが取り組まない問題に対処する必要があるため、プライベートメソッドの場合はさらに重要になる可能性があります。

おそらく IDE には、開発者が重要で現在のメソッドに適用可能なさまざまなプロパティをチェックできるように、文書化フォームを使用できる機能が必要です。

score 0 · Accepted Answer

javadoc コメントを持たないコードに対して javadoc を実行できます。メソッドとパラメーターに適切な名前を付ければ、かなり使いやすい javadoc が生成されます。

score 0 · Accepted Answer

以前の会社では、eclipse でジャロピーコードフォーマッターを使用していました。これにより、private を含むすべてのメソッドに javadoc が追加されます。

セッターとゲッターを文書化するのは困難でした。しかし、なんてこった。あなたはそれをしなければなりません-あなたはそれをします。そのおかげで、XEmacs でいくつかのマクロ機能を学ぶことができました :-) ANTLR 作成者が数年前に行ったように、Java パーサーとコメンターを作成することで、さらに自動化できます :-)

現在、すべてのパブリックメソッドと 10 行を超えるものを文書化しています。

score 0 · Accepted Answer

少なくともすべての public および interface プロパティとメソッドを文書化して、私のコードを呼び出している人が何が何であるかを理解できるようにしています。また、メンテナンスのためにも、できる限りコメントするようにしています。自分のためだけに自分の時間に行う「個人的な」プロジェクトでさえ、1年間棚上げして後で戻ってくる可能性があるという理由だけで、javadocを試みます。

java - 作成するすべてのメソッドにJavadocを使用していますか？

19 に答える 19

Related

Reference