web-dev-qa-db-ja.com

プライベート/保護されたメソッドのJavaDoc？

privateまたはprotectedメソッドのJavaDocを書く必要がありますか？そして、private変数についてはどうでしょうか？

Java bookとprivate変数はJavaDoc'edです。したがって、JavaDocの良い習慣かどうかはわかりません。 private（またはprotected）メソッド。

javajavadocprivateprotected
45
smartmouse

はい、プライベートメソッド用のJavaDocを作成する必要があります。それが自分専用の場合でもです。コードを変更する必要がある3年間で、ドキュメントを作成できたことをうれしく思います。

会社を辞めたり、別のプロジェクトに取り組む必要がある場合、同僚はドキュメント化されたコードを持って喜んでいます。文書化されていないコードには、はるかに低い価値があります。

そして、実際の専門家がそれをどのように行うかを見てください。 Sun Microsystems によるArrayListクラスのソースコードからの抜粋です。

 /**
  * The array buffer into which the elements of the ArrayList are stored.
  * The capacity of the ArrayList is the length of this array buffer.
  */
  private transient Object[] elementData;
51
AlexWien

最初に自問する必要がある質問は、「JavaDocsを作成する理由」です。彼らは誰のために役立ちますか？誰があなたにそれらを書くように頼みましたか？

ほとんどの場合、誰か（雇用主/教授）があなたの方法のいくつかを文書化するようにあなたに頼みました。これは一般的に良いことですが、追加のメンテナンスというコストが伴います。

ドキュメントの公開バージョンを持っている場合（エンドユーザー向けにドキュメントを生成してオンラインで公開している場合など）、エンドユーザーが何かを文書化するのは理にかなっています know。これには、すべてのパブリッククラスとメソッドが含まれます。

あなた自身や他の開発者はどうですか？

私の意見では内部およびプライベートのメソッドとクラスでjavadocsを使用するべきではありません。主な理由は、javadocsが主にコードを維持するのではなく、消費する人々に利益をもたらすからです。

一方、多くの場合、内部にある独自のコードにメモやコメントを保存する必要があります。この場合、通常のコメントを提案します（例：//）代わりに;メンテナンスが少なく、多くの場合、同じように明確で、タイピングがはるかに少なくなります。

一方、メソッドがパブリックになった場合、それらのコメントを真のjavadocsに変換すると便利です。 Javadocには、すべてのパラメーター、例外、および戻り値について考える（文書化する）ことを強いる利点があります。

トレードオフはあなた次第です。

38
ashes999

いいえ、プライベートメソッド用にjavadocを書くべきではありません。エンドユーザーはプライベートフィールドやメソッドにアクセスできないため、エンドユーザーにjavadocを提供する意味はありません。プライベートフィールドとメソッドは、開発者専用です。本当に必要な場合は、非自明なロジックについてコメントを自由に書いてください。おそらくprotectedメソッドのjavadocを記述する必要があります。これらのメソッドはオーバーライドされる場合があり、ユーザーにメソッドの実行内容または実行内容に関する情報を提供すると役立つためです。

6
Josh M

最良の場合、コメントは単にnecessaryであってはならないという一般的な推奨事項をよく耳にします。ただし、JavaDocについては、開発者だけでなくライブラリのユーザーにとっても重要な役割を果たします。

さらに、JavaDocコメントを書くことは、他の誰よりもあなたにとって（特に初心者にとって）便利かもしれません：変数とは何か、メソッドが単一の_/** One-line-JavaDoc comment */_で何をするのかを説明するのが難しいと感じたら、自動的にそこで行ったことを再考します。

JavaDocを生成するとき、APIのpublic部分とprotected部分に対してのみ生成するか、default-またはprivate要素に対して生成するかを選択できます。

ただし、いずれの場合もprotectedメソッドをドキュメント化する必要があります。クラスを拡張する誰かcallこのメソッド、またはこのメソッドをオーバーライドすることもできますか？もしそうなら、彼が知っておくべき事前条件と事後条件はありますか？オーバーライドされたバージョンでsuper.theMethod()を呼び出す必要がありますか？ （ところで：彼がメソッドをオーバーライドすることを許可されていない場合、それはfinalであるはずですが、とにかく文書化されています）

ところで：私は個人的にeverythingをコメントしていますが、ほとんどの人は、特に「些細な」ことのために、それは必要ではなく、悪いスタイルでさえあると思うことを知っています

_/**
 * The number of elements in this set
 */
private final int numberOfElements;
_

害はないと思いますが、多くの場合に役立ちます。おそらく、privateパーツに関しては、単なる好みの問題です。

5
Marco13

Javadocを使用する必要はありませんが、非常に役立ちます。多くのjavadocが決して悪いことではありません。

質問ごとに、javadocドキュメンテーションコンパイラを使用すると、javadocsは保護されたメソッド用にコンパイルされますが、プライベートメソッド用にはコンパイルされません。ただし、コードコメントとして使用できない理由はありません。

3
Peter Bratton