web-dev-qa-db-ja.com

Javadocコメント対ブロックコメント？

メソッドの先頭でブロックコメントを使用するのが適切な場合と、javadocスタイルのコメントを使用するのが適切な場合

Javaスタイルガイド の「コメント」セクションから、私はこれを見つけました：

Javaプログラムには、実装コメントとドキュメントコメントの2種類のコメントを含めることができます。実装コメントは、C++にあるコメントで、/*...*/と//で区切られています。文書コメント（「文書コメント」と呼ばれる）はJava専用であり、/**...*/で区切られます。 docコメントは、javadocツールを使用してHTMLファイルに抽出できます。

実装コメントは、コードをコメントアウトするため、または特定の実装に関するコメントのためのものです。 Docコメントは、実装の観点から、コードの仕様を説明するためのものです。必ずしもソースコードを手元に持っているとは限らないかもしれない開発者に読まれます。

だから、私の質問を表現する別の方法は次のようになります：メソッドは、特定の実装に関するコメントではなく、実装フリーの観点（Javadoc）から、コードの仕様に値するのはいつですか？インターフェイスはjavadocコメントを取得し、実装はブロックコメントを取得しますか？

edit：これまでの回答に基づいて、質問を正確に伝えていないと思います。

これが私が知りたいことの例です。

/**
 * Javadoc comment here about general implementation?
 */
/*
 * Should I now have a separate block comment for my specific implementation?
 */
public void foo()
{
...
}

2つの異なるコメントスタイルは、2種類の情報を伝えます。メソッドに両方の先行javadocコメントと先行ブロックコメントを含める必要がある場合はありますか？

質問することへのインスピレーションは、Eclipseが今私のためにこれを自動生成したことです：

/*
 * (non-Javadoc)
 * @see my.package#process()
 */

そして、私はここで何らかのスタイリングが行われていると考えましたが、これは私が上記でリンクしているコメント仕様で具体的に宣言されていません。

javacomments
34
Tony Stark

クラスのユーザーが知っておく必要がある情報は、Javadocコメントに入れる必要があります。

クラスを変更する開発者が通常のコメント（ブロックまたは行）に入ることを知る必要があるという情報。

そして、コードのブロック（クラス、インターフェース、フィールド、メソッド、コンストラクターなど）がboth Javadocコメントと通常のコメントブロックを持つ可能性があります。内部文書が必要です。

個人的には、Javadoc以外のコメントをほとんど書かない傾向があります。自己文書化するようにコードを構造化することを好みます。

65
Joachim Sauer

私の意見では、Javadocコメントは、コードを使用し、メソッドを呼び出す人々に書き込むコメントです。

Javadocコメントは、メソッドのパラメーターに重点を置いています。メソッドに返すパラメーターは、メソッドに与えるパラメーターによって異なります。

ブロックコメントは、内部のコメントであり、コードを保守する人々のために作成するコメントです。

ブロックコメントは、コードがどのように機能するのか、なぜ機能するのか、実際の作業を行うために使用される操作を理解するために重要です。

12
Vivien Barousse

私の意見では、ブロックのコメントをメソッドの先頭に置くことは意味がありません（まあ、絶対に言ってはいけませんが、少なくともほとんどの時間は）。インターフェイスメソッドに関するJavadocコメントはコントラクトを指定し、クラスメソッドでは実装について通知するため、ユーザーは、単一のインターフェイスを実装するクラスが複数ある場合に使用するクラスを決定できます。 Listインターフェイスについて考えてください。実装ArrayListとLinkedListは異なるユースケースに適しているため、それぞれのドキュメントで長所と短所を説明できます。

私は非常に具体的なことについてのブロックコメントをインラインします。実装がどこにあるか、実装固有のドキュメントが直接必要です。もちろん、できるだけまれに使用する必要があります。表現力豊かな変数名とメソッド名を使用すると、低レベルのドキュメントが自動的に追加されます。

Eclipseの自動生成されたブロックコメントは、不足しているアスタリスクを追加することにより、Javadocコメントに記入し、潜在的にそれらを作成するためのものです。どのケースで表示されるかは正確にはわかりませんが、既存のクラスからインターフェイスを抽出する場合です。次に、クラスのJavadocがインターフェイスメソッドに移動し、クラスメソッドがブロックコメントを取得します。この背後にある理由は、多くの場合、インターフェイスを実装するときに追加する必要のあるものがあまりないことです。ここでも例としてListを使用します。 size()メソッドは、ArrayListおよびLinkedList実装のドキュメントをこれ以上必要としません。追加する価値はありません。もちろん、この例は実際の実装（少なくともOpenJDKの）doにJavadocが含まれていますが、その必要はなく、実際に価値のあるものは追加しません。さらに悪いことに、インターフェイスのドキュメントよりも少ない情報しか提供しません。

3
musiKk