使用Java注释

Java comments are notes in a Java code file that are ignored by the compiler and runtime engine. They are used to annotate the code in order to clarify its design and purpose. You can add an unlimited number of comments to a Java file, but there are some "best practices" to follow when using comments.

Java注释是Java代码文件中的注释，编译器和运行时引擎会忽略它们。 它们用于对代码进行注释，以阐明其设计和目的。 您可以在Java文件中添加无限数量的注释，但是使用注释时要遵循一些“最佳实践”。

Generally, code comments are "implementation" comments that explain the source code, such as descriptions of classes, interfaces, methods, and fields. These are usually a couple of lines written above or beside Java code to clarify what it does.

通常，代码注释是解释源代码的 “实现”注释，例如类，接口，方法和字段的描述。 这些通常是在Java代码上方或旁边编写的几行，以阐明其功能。

Another type of Java comment is a Javadoc comment. Javadoc comments differ slightly in syntax from implementation comments and are used by the program javadoc.exe to generate Java HTML documentation.

另一种Java注释是Javadoc注释。 Javadoc注释的语法与实现注释略有不同，程序javadoc.exe使用Javadoc注释生成Java HTML文档。

为什么要使用Java注释？ ( Why Use Java Comments? )

It's good practice to get into the habit of putting Java comments into your source code to enhance its readability and clarity for yourself and other programmers. It isn't always instantly clear what a section of Java code is performing. A few explanatory lines can drastically reduce the amount of time it takes to understand the code.

养成将Java注释放入源代码中的习惯，这是一种好习惯，以提高您自己和其他程序员的可读性和清晰度。 并非总是立即就能清楚地知道一段Java代码正在执行什么。 一些说明行可以大大减少理解代码所花费的时间。

它们会影响程序的运行方式吗？ ( Do They Affect How the Program Runs? )

Implementation comments in Java code are only there for humans to read. Java compilers don't care about them and when compiling the program, they just skip over them. The size and efficiency of your compiled program will not be affected by the number of comments in your source code.

Java代码中的实现注释仅供人们阅读。 Java编译器不在乎它们，并且在编译程序时 ，它们只是跳过它们。 您的编译程序的大小和效率不会受到源代码中注释数量的影响。

实施意见 ( Implementation Comments )

Implementation comments come in two different formats:

实施注释有两种不同的格式：

• Line Comments: For a one line comment, type "//" and follow the two forward slashes with your comment. For example:

  行注释：对于一行注释，请键入“ //”，并在注释后面加上两个正斜杠。 例如：

   // this is a single line comment int guessNumber = (int) (Math.random() * 10); When the compiler comes across the two forward slashes, it knows that everything to the right of them is to be considered as a comment. This is useful when debugging a piece of code. Just add a comment from a line of code you are debugging, and the compiler won't see it:

  •  // this is a single line comment // int guessNumber = (int) (Math.random() * 10); You can also use the two forward slashes to make an end of line comment:

  •  // this is a single line comment int guessNumber = (int) (Math.random() * 10); // An end of line comment 

  Line Comments: For a one line comment, type "//" and follow the two forward slashes with your comment. For example:

  行注释：对于一行注释，请键入“ //”，并在注释后面加上两个正斜杠。 例如：

   // this is a single line comment int guessNumber = (int) (Math.random() * 10); When the compiler comes across the two forward slashes, it knows that everything to the right of them is to be considered as a comment. This is useful when debugging a piece of code. Just add a comment from a line of code you are debugging, and the compiler won't see it:

• Block Comments: To start a block comment, type "/*". Everything between the forward slash and asterisk, even if it's on a different line, is treated as a comment until the characters "*/" end the comment. For example:

  阻止注释：要开始阻止注释，请键入“ / *”。 正斜杠和星号之间的所有内容(即使在不同的行上)都被视为注释，直到字符“ * /”结束注释为止。 例如：

   /* this  is  a block comment */  /* so is this */ 

Javadoc注释 ( Javadoc Comments )

Use special Javadoc comments to document your Java API. Javadoc is a tool included with the JDK that generates HTML documentation from comments in source code.

使用特殊的Javadoc注释来记录您的Java API。 Javadoc是JDK附带的工具，可从源代码中的注释生成HTML文档。

A Javadoc comment in 

中的Javadoc注释

.java source files is enclosed in start and end syntax like so: 

/** and 

*/. Each comment within these is prefaced with a 

*

Place these comments directly above the method, class, constructor or any other Java element that you want to document. For example:


Javadoc incorporates various tags that control how the documentation is generated. For example, the 
@param
 tag defines parameters to a met


Many other tags are available in Javadoc, and it also supports HTML tags to help control the output. See your Java documentation for more detail.

 
  Tips for Using Comments  

*

Place these comments directly above the method, class, constructor or any other Java element that you want to document. For example:


Javadoc incorporates various tags that control how the documentation is generated. For example, the 
@param
 tag defines parameters to a met


Many other tags are available in Javadoc, and it also supports HTML tags to help control the output. See your Java documentation for more detail.

 
  Tips for Using Comments  

• Don't over comment. Every line of your program does not need to be explained. If your program flows logically and nothing unexpected occurs, don't feel the need to add a comment.

  不要过度评论。 程序的每一行都不需要解释。 如果您的程序在逻辑上运行并且没有意外发生，请不要添加注释。

• Indent your comments. If the line of code you are commenting is indented, make sure your comment matches the indentation.

  缩进您的评论。 如果您要注释的代码行缩进，请确保您的注释与缩进匹配。

• Keep comments relevant. Some programmers are excellent at modifying code, but for some reason forget to update the comments. If a comment no longer applies, then either modify or remove it.

  保持评论相关。 一些程序员擅长修改代码，但是由于某种原因忘记更新注释。 如果评论不再适用，则可以对其进行修改或删除。

• Don't nest block comments. The following will result in a compiler error:

  不要嵌套块注释。 以下将导致编译器错误：

   /* this  is /* This block comment finishes the first comment */ a block comment */ 

翻译自: https://www.thoughtco.com/java-comments-using-implementation-comments-2034198