最初の形式は Javadoc です。あなたがjavadocツールによって生成されるあなたのコードのための正式なAPIを書いているとき、あなたはこれを使います。たとえば、 Java 7 APIページ はJavadocを使用し、そのツールによって生成されました。
Javadocでよく見られる要素は次のとおりです。
@param：これはどのパラメータがメソッドに渡されているのか、そしてどのような値が期待されているのかを示すために使われます。@return：これは、メソッドがどのような結果を返すのかを示すために使用されます。@throws：これは、特定の入力の場合にメソッドが例外またはエラーをスローすることを示すために使用されます。@since：これは、このクラスまたは関数が利用可能だった最も古いJavaのバージョンを示すために使用されます。
例として、compareのIntegerメソッドのJavadocを次に示します。
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}
2番目の形式はブロック（複数行）コメントです。コメントに複数の行を含める場合はこれを使用します。
私はあなたが後者の形式控えめにを使いたいだけだと言うでしょう。つまり、method/complex関数がどのような動作をするのかを記述していないブロックコメントでコードに負担をかけたくないということです。
Javadocはこの2つをよりわかりやすく説明したものであり、それを使用することで実際のドキュメントを生成することができるので、単純なブロックコメントよりもJavadocを使用する方が望ましいでしょう。
Java プログラミング言語 の場合、両者の間に 差はありません があります。 Javaには、2種類のコメントがあります。伝統的なコメント（/* ... */）と行末コメント（// ...）です。 Java言語仕様 を参照してください。したがって、Javaプログラミング言語では、/* ... */と/** ... */の両方が従来のコメントのインスタンスであり、それらは両方ともJavaコンパイラによってまったく同じに扱われます。
ただし、Javaプログラマとしては、Javaコンパイラを使用するだけではありません。あなたは全体のツールチェーンを使用します。コンパイラ、IDE、ビルドシステムなど。これらのツールの中には、Javaコンパイラとは異なる解釈をするものがあります。特に、/** ... */のコメントはJavadocツールによって解釈されます。このツールは、Java platform に含まれており、ドキュメントを生成します。 JavadocツールはJavaソースファイルをスキャンし、/** ... */の間の部分をドキュメントとして解釈します。
これはFIXMEやTODOのようなタグに似ています。// TODO: fix thisや// FIXME: do thatのようなコメントを含めると、ほとんどのIDEはそのようなコメントを強調表示するので、忘れないでください。しかし、Javaの場合、それらは単なるコメントです。
最初はJavadocのコメントです。それらはあなたのクラスのためのAPIドキュメントを生成するためにjavadocツールによって処理されることができます。 2番目は通常のブロックコメントです。
JLSの3.7 を読んで、Javaのコメントについて知っておくべきことをすべて説明してください。
2種類のコメントがあります。
- / *テキスト* /
伝統的なコメント：ASCII文字/ *からASCII文字* /までのテキストはすべて無視されます（CおよびC++の場合と同様）。
- //テキスト
行末コメント：ASCII文字//から行末までのすべてのテキストは無視されます（C++の場合と同様）。
あなたの質問について、
最初の1つ
/**
*
*/
Javadoc Technology を宣言するために使用されます。
Javadocは、一連のソースファイル内の宣言とドキュメンテーションコメントを解析し、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドを記述する一連のHTMLページを生成するツールです。 Javadocドックレットを使用してJavadoc出力をカスタマイズできます。ドックレットは、ドックレットAPIを使用して作成されたプログラムで、ツールによって生成される出力の内容と形式を指定します。 HTML、SGML、XML、RTF、MIFなど、あらゆる種類のテキストファイル出力を生成するためのドックレットを作成できます。オラクル社は、HTML形式のAPIドキュメントを生成するための標準ドックレットを提供しています。ドックレットを使用して、APIドキュメントの作成に関連しない特別なタスクを実行することもできます。
Docletの詳細については、 API を参照してください。
2番目のものは、JLSで明確に説明されているように、/*と*/の間のすべてのテキストを無視するため、複数行のコメントを作成するために使用されます。
Javaのコメントについて知りたいことが他にもあります
- コメントは入れ子になりません。
/* and */で始まるコメントでは、//に特別な意味はありません。//で始まるコメントには、/* or /**は特別な意味はありません。- 字句文法は、コメントが文字リテラル（ §3.10.4 ）または文字列リテラル（ §3.10.5 ）の中に現れないことを意味します。
したがって、次のテキストは単一の完全なコメントです。
/* this comment /* // /** ends here: */
既存の答えが質問のこの部分に適切に対処したとは思わない：
いつ使用するべきですか？
組織内で公開または再利用されるAPIを作成する場合は、すべてのpublicクラス、メソッド、およびフィールド、およびprotectedメソッドおよびフィールドのnon- -finalクラス。 Javadocは、前提条件、事後条件、有効な引数、実行時例外、内部呼び出しなど、メソッドシグネチャで伝達できないすべてをカバーする必要があります。
内部API（同じプログラムの異なる部分で使用されるAPI）を作成している場合、Javadocはおそらくそれほど重要ではありません。ただし、メンテナンスプログラマの利益のために、正しい使用法や意味がすぐにはわからないメソッドやフィールドについては、Javadocを記述する必要があります。
Javadocの「キラー機能」は、Eclipseや他のIDEと密接に統合されていることです。開発者は、マウスポインターを識別子の上に置くだけで、それについて知る必要があるすべてのことを学習できます。常にドキュメントを参照することは、経験豊富なJava開発者にとって第2の性質になり、独自のコードの品質が向上します。 APIがJavadocで文書化されていない場合、経験豊富な開発者は使用したくないでしょう。
次のJavaコードのリストにあるコメントは、グレー表示されている文字です。
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}
Java言語は3種類のコメントをサポートします。
/* text */
コンパイラは/*から*/までのすべてを無視します。
/** documentation */
これはドキュメンテーションコメント（略してdocコメント）を示します。 /*と*/を使用するコメントを無視するのと同じように、コンパイラはこの種のコメントを無視します。 JDKのjavadocツールは、自動生成されたドキュメントを準備するときにドキュメントのコメントを使用します。
// text
コンパイラは//から行末までのすべてを無視します。
今、あなたがそれらをいつ使用すべきかに関して：
1行のコードをコメントにしたい場合は// textを使用してください。
複数行のコードをコメントアウトしたい場合は/* text */を使用してください。
プログラム文書の自動生成に使用できるプログラムに関する情報を追加したい場合は、/** documentation */を使用してください。
1つは、クラス、インタフェース、メソッドなどの上にJavadocを定義することです。Javadocを名前として使用して、クラスの動作やメソッドの動作などについてコードを文書化し、それに関するレポートを生成できます。
2つ目はコードブロックコメントです。たとえば、コンパイラに解釈させたくないコードブロックがある場合、コードブロックコメントを使用します。
もう1つは//これです。これはステートメントレベルで使用し、後続のコード行の動作を指定します。
// TODOのような他のものもあります、これはあなたが後でその場所で何かをしたいことを示します
// FIXME一時的な解決策がある場合に使用できますが、後でアクセスしてそれを改善したい場合に使用します。
お役に立てれば
- シングルコメント例：//コメント
- 複数行コメント（例：/ * comment * /）
- javadocのコメント例：/ ** comment * /