Correct use of annotations in java

Java provides 3 types of comments:

Single-line comments (C++ style)

The simplest comments in Java are single-line comments. It starts with two forward slashes and ends at the end of the line. For example:

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

Multi-line comments (C style)

Java also provides comment types that span multiple lines. This type of comment begins with a forward slash followed by an asterisk and ends with an asterisk followed by a forward slash. The starting and ending delimiters for this type of comment can be on the same line or on different lines. For example:

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

Note: C-style comments cannot be nested. For example, the following usage:

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

The above usage will cause a syntax error, because the Java compiler only treats the first */ as a comment. (The compiler considers the comment to end at the first "*/").

You can embed single-line comments in multi-line comments:

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

and use multi-line comments in single-line comments:

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

Documentation comments

Documentation comments are a special comment that are very similar to multi-line comments. It can be used to generate external documentation for your source code. This comment begins with a forward slash followed by two asterisks and ends with an asterisk followed by a forward slash. For example:

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

Here are some important things to note about documentation comments:

The javadoc documentation generator will add all the text in the documentation comment into an HTML paragraph. This means that any text within a documentation comment will be formatted as a paragraph; spaces and newlines will be ignored. If you want special formatting, you must use HTML tags in documentation comments.

If a documentation comment starts with more than two asterisks, then javadoc assumes that these asterisks are used to create a "box" around the comment in the source code, and ignores the extra asterisks. For example:

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

This comment only retains the "This is the start of a method" text.

javadoc ignores asterisks at the beginning of lines in documentation comments. For example:

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

This comment only retains the text "This is a doc comment on multiple lines that I want to stand out in source code, looking "neat"".

Common usage is as follows:

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

This usage is to highlight the comment. Note that this is a documentation comment (even if it's not what you think), and the content of the comment will appear in the generated documentation.

When to use documentation comments

You should (at least) use documentation comments before any public class, interface, method, and class or instance variable in the source code. This allows javadoc to generate simple documentation for the code, which lists the public entities and a brief description of each entity. You can also use documentation comments before non-public methods, but you need to use a javadoc option to document them. Using documentation comments on non-public entities is less important than on public entities (its interface is not exposed...). But if you want to comment code, you can also use documentation comments.

When to use single-line comments

Any time!

Regarding comments, I have a simple suggestion. Use single-line comments when you want to write regular comments (not documentation comments describing classes, interfaces, methods, or variables).

Why? Because you can easily "comment out" your code segment using multi-line comments ("commenting out code" means changing the lexical status of a piece of code into a comment, allowing the compiler to ignore this piece of code). For example:

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个最有趣的代码注释，尽管它是搞笑的。

什么时候使用多行注释

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