Proper use of annotations in Java

Java provides 3 types of annotations:

Single-line Comments (C + + style)

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

This is a single-line commentx = 1; A single-line comment after code

Multiline comment (c-style)

Java also provides annotation types that span multiple lines. This type of comment begins with a forward slash followed by an asterisk and ends with an asterisk immediately following a forward slash. The start and end 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 annotations cannot be nested. For example, the following usage:

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

The above usage can cause syntax errors, because the Java compiler only handles the first */as a comment. (the compiler thinks the comment ends at the first "*/").

You can embed a single line comment in a multiline comment:

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

and using multiline comments in a single-line comment:

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

Document comments

A document comment is a special comment that is similar to a multiline comment, which can be used to generate external documents for your source code. The comment begins with a forward slash followed by two asterisks and ends with an asterisk followed by a forward slash. For example:

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

Here are some important things to note about document annotations:

• The Javadoc document Builder adds all the text in the document's comments to an HTML paragraph. This means that any text in a document comment is formatted as a paragraph, and spaces and line breaks are ignored. If you want a special format, you have to use HTML tags in the document comments.

• If the document comment starts with an asterisk of more than two, then Javadoc thinks the asterisk is used to create a "box" box in the source code and ignores the extra asterisk. For example:

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

The note only retains the "this is the start of a method" text.

• Javadoc ignores asterisks at the beginning of the document comment. For example:

/*************************************** * This was a doc comment * on multiple lines that I want to stand * out in Source Code, looking "neat" ***************************************/

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

• Common usage is as follows:

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

This usage is intended to highlight annotations. Note that this is a document comment (even if it is not what you think), and it will appear in the resulting document with the contents of the comment.

When to use document annotations

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

when to use a single-line comment

Any time you can!

For comments, I have a simple suggestion that you can use a single-line comment when you want to write a regular comment (not a document comment that describes a class, interface, method, or variable).

Why? Because you can easily use multi-line annotations to "comment out" Your code snippet ("Comment out code" means to change the lexical state of a piece of code into a comment and let the compiler ignore the code). As an example:

x = 1;   /* Set X to 1 */y = 2;   /* Set Y to 2 */f (x, y); /* call F with x and Y */

To comment out the above three lines of code, you might need to use a single-line comment before each line:

x = 1;   /* Set X to 1 *///y = 2;   /* Set Y to 2 *///f (x, y); /* call F with x and Y */

Or add a multiline comment where there is no comment:

/* x = 1;  */* Set X to 1 *//* y = 2;  */* Set Y to 2 *//* f (x, y); */* call F with x and Y */

Or break down or delete the "end comment" separator for an existing comment:

/*x = 1;   /* Set X to 1 */y = 2;   /* Set Y to 2 */f (x, y); /* call F with x and Y */*/

These usages are awful. If the original code uses the following comments, then things are much better:

x = 1;   Set X to 1y = 2;   Set Y to 2f (x, y); Call F with X and Y

As a result, you can easily comment out the code by just wrapping it around with a multiline comment:

/*x = 1;   Set X to 1y = 2;   Set Y to 2f (x, y); Call F with X and y*/

Use single-line comments when you need to use annotations, and don't write useless comments.

You can also take a look at the 9 most interesting code comments that were previously released, even though it's hilarious.

when to use multi-line annotations

After reading the above, the problem became apparent. Use only a multiline comment to comment on the snippet, not for any other purpose.

Proper use of annotations in Java