Java でのアノテーションの正しい使用

Java は 3 種類のコメントを提供します:

単一行コメント (C++ スタイル)

Java で最も単純なコメントは単一行コメントです。 2 つのスラッシュで始まり、行の終わりで終わります。例:

// this is a single-line comment
 
x = 1; // a single-line comment after code

複数行コメント (C スタイル)

Java は複数行にまたがるコメント タイプも提供します。このタイプのコメントは、スラッシュとアスタリスクで始まり、アスタリスクとスラッシュで終わります。このタイプのコメントの開始区切り文字と終了区切り文字は、同じ行に置くことも、別の行に置くこともできます。例:

/* This is a c-style comment */
 
/*  This is also a
 
    c-style comment, spanning
 
    multiple lines */

注: C スタイルのコメントはネストできません。たとえば、次の使用法は次のとおりです。

/* A comment looks like
   /* This is a comment */
   blah blah blah
 */

Java コンパイラーは最初の */ のみをコメントとして扱うため、上記の使用法では構文エラーが発生します。 (コンパイラーは、コメントが最初の「*/」で終了するとみなします)。

複数行のコメントに単一行のコメントを埋め込むことができます:

/* This is a single-line comment:
 
    // a single-line comment
 
 */

、単一行のコメントで複数行のコメントを使用できます:

// /* this is
 
//    a multi-line
 
//    comment */

ドキュメントのコメント

ドキュメントのコメントは、以下に非常によく似た特別なコメントです。複数行のコメントを使用して、ソース コードの外部ドキュメントを生成できます。このコメントは、スラッシュとそれに続く 2 つのアスタリスクで始まり、アスタリスクとそれに続くスラッシュで終わります。例:

/** This is a documentation comment */
 
/** This is also a
 
    documentation comment */

ドキュメント コメントについて注意すべき重要な点がいくつかあります:

javadoc ドキュメント ジェネレーターは、ドキュメント コメント内のすべてのテキストを HTML 段落に追加します。これは、ドキュメント コメント内のテキストは段落としてフォーマットされ、スペースと改行は無視されることを意味します。特別な書式設定が必要な場合は、ドキュメントのコメントで HTML タグを使用する必要があります。

ドキュメントのコメントが 3 つ以上のアスタリスクで始まっている場合、javadoc はこれらのアスタリスクがソース コード内のコメントの周囲に「ボックス」を作成するために使用されていると想定し、余分なアスタリスクを無視します。例:

/**********************************
 
   This is the start of a method
 
**********************************/

このコメントには、「これはメソッドの始まりです」というテキストのみが保持されます。

javadoc は、ドキュメントのコメント内の行頭のアスタリスクを無視します。例:

/***************************************
 
 * This is a doc comment
 
 * on multiple lines that I want to stand
 
 * out in source code, looking "neat"
 
 ***************************************/

このコメントは、「これはソース コード内で目立たせたい複数行の doc コメントであり、「きちんと」見えるようにする」というテキストのみを保持します。

一般的な使用法は次のとおりです:

/******************************************
 
   ...
 
 ******************************************/

この使用法はコメントを強調表示することです。これはドキュメント コメントであり (たとえそれがあなたが思っているものと異なっていても)、コメントの内容は生成されるドキュメントに表示されることに注意してください。

ドキュメント コメントを使用する場合

ソース コード内のパブリック クラス、インターフェイス、メソッド、クラス変数またはインスタンス変数の前に (少なくとも) ドキュメント コメントを使用する必要があります。これにより、javadoc は、パブリック エンティティと各エンティティの簡単な説明をリストしたコードの簡単なドキュメントを生成できるようになります。非パブリック メソッドの前にドキュメント コメントを使用することもできますが、それらをドキュメント化するには javadoc オプションを使用する必要があります。非パブリック エンティティでドキュメント コメントを使用することは、パブリック エンティティほど重要ではありません (インターフェイスは公開されていません...)。ただし、コードにコメントを付けたい場合は、ドキュメント コメントを使用することもできます。

単一行コメントを使用する場合

いつでも!

コメントに関して、簡単な提案があります。通常のコメントを書きたい場合は、単一行のコメントを使用してください (クラス、インターフェイス、メソッド、または変数を説明するドキュメント コメントではありません)。

なぜですか？複数行のコメントを使用してコード セグメントを簡単に「コメント アウト」できるためです (「コードのコメント アウト」とは、コードの一部の字句ステータスをコメントに変更し、コンパイラがこのコードを無視できるようにすることを意味します)。例:

x = 1;   /* set x to 1 */
 
y = 2;   /* set y to 2 */
 
f(x, y); /* call f with x and y */

要把上面三行代码注释掉，你可能需要在每一行的前面使用单行注释：

// x = 1;   /* set x to 1 */
 
// y = 2;   /* set y to 2 */
 
// f(x, y); /* call f with x and y */

或者在还没有加注释的地方加上多行注释：

/* x = 1;  */ /* set x to 1 */
 
/* y = 2;  */ /* set y to 2 */
 
/* f(x, y);*/ /* call f with x and y */

或者分解或删除已存在的注释的“结束注释”分解符：

/*
 
x = 1;   /* set x to 1 * /
 
y = 2;   /* set y to 2 * /
 
f(x, y); /* call f with x and y * /
 
*/

这些用法都糟糕透了。如果原始代码使用下面的注释，那么事情就好办多了：

x = 1;   // set x to 1
 
y = 2;   // set y to 2
 
f(x, y); // call f with x and y

如此一来，只需使用多行注释把代码围起来你就可以轻松把它注释掉：

/*
 
x = 1;   // set x to 1
 
y = 2;   // set y to 2
 
f(x, y); // call f with x and y
 
*/

在你需要使用注释的时候尽量使用单行注释，不要写无用的注释。

你也可以看看之前发布的9个最有趣的代码注释，尽管它是搞笑的。

什么时候使用多行注释

阅读了上面的内容后，这个问题变得很明显了。只使用多行注释来注释代码段，不要用以其他目的。