Java 简明教程

Java Comments

Java Comments

*Java comments*是代码中用来解释源代码的文本注释。注释可用于解释逻辑，或用于编写文档。编译器不会编译注释。在 Java 中，注释与 C 和 C++ 非常相似。

Java comments are text notes written in the code to provide an explanation about the source code. The comments can be used to explain the logic or for documentation purposes. The compiler does not compile the comments. In Java, comments are very similar to C and C++.

在 Java 中，有三种类型的注释：

In Java, there are three types of comments:

  1. Single-line comments

  2. Multiline comments

  3. Documentation comments

我们逐一详细讨论每种类型的注释。

Let’s discuss each type of comment in detail.

1. Single Line Comment

单行注释仅用于在一行上添加注释，可以使用两个正斜杠 (//) 编写。这些注释是最常用的注释方式。

The single-line comment is used to add a comment on only one line and can be written by using the two forward slashes (//). These comments are the most used commenting way.

单行注释是解释行目的（或添加文本注释）的最常用注释方法。

The single line comments are the most used commenting way to explain the purpose (or to add a text note) of the line.

Syntax

考虑以下语法在 Java 中编写单行注释：

Consider the below syntax to write a single line comment in Java:

// comment

Example 1: Java Single Line Comment

// if divisor is 0 throw an exception
if (divisor == 0) {
   throw new IllegalArgumentException("divisor cannot be zero");
}

Example 2: Java Single Line Comment

下述代码显示了在简单程序中使用单行注释。我们已向代码行添加注释以解释其目的。

Following code shows the usage of single line comments in a simple program. We’ve added comments to code lines to explain their purpose.

package com.tutorialspoint;

public class MyFirstJavaProgram {
   public static void main(String[] args) {
     MyFirstJavaProgram program = new MyFirstJavaProgram();
     double result = program.divide(100, 10);
     System.out.println(result);
   }

   private double divide(int dividend, int divisor) throws IllegalArgumentException {
      // if divisor is 0 throw an exception
      if (divisor == 0) {
         throw new IllegalArgumentException("divisor cannot be zero");
      }
      return (double) dividend / divisor; // returns the result of the division as double
   }
}

编译并运行 MyFirstJavaProgram。这将产生以下结果 -

Compile and run MyFirstJavaProgram. This will produce the following result −

10.0

2. Multiline Comment

多行（或多行）注释以斜杠后跟星号 (/) and end with an asterisk followed by a forward slash (/) 开头，用于添加多行注释。

The multiline (or, multiple-line) comments start with a forward slash followed by an asterisk (/) and end with an asterisk followed by a forward slash (/) and they are used to add comment on multiple lines.

当我们想要添加跨越多行的长注释或注释掉完整代码时，多行注释非常有用。

The multiline comments are very useful when we want to put a long comment spreading across multiple lines or to comment out the complete code.

Syntax:

考虑以下语法在 Java 中编写多行注释：

Consider the below syntax to write multiline comment in Java:

/*
Comment (line 1)
Comment (line 2)
...
*/

Example 1: Java Multiline Comment

/* This is an example
of
multi line comment. */

/* if (dividend == 0) {
   throw new IllegalArgumentException("dividend cannot be zero");
} */

Example 2: Java Multiline Comment

下述代码显示了在简单程序中使用多行注释。我们已使用多行注释从方法中注释掉额外代码。

Following code shows the usage of multiple comments in a simple program. We’ve commented out extra code from a method using Multiline comments.

package com.tutorialspoint;

public class MyFirstJavaProgram {
   public static void main(String[] args) {
      MyFirstJavaProgram program = new MyFirstJavaProgram();
      double result = program.divide(100, 10);
      System.out.println(result);
   }

   private double divide(int dividend, int divisor) throws IllegalArgumentException {
      if (divisor == 0) {
         throw new IllegalArgumentException("divisor cannot be zero");
      }
      /* if (dividend == 0) {
         throw new IllegalArgumentException("dividend cannot be zero");
      } */
      return (double) dividend / divisor;
   }
}

编译并运行 MyFirstJavaProgram。这将产生以下结果 -

Compile and run MyFirstJavaProgram. This will produce the following result −

10.0

3. Documentation Comment

文档注释用于编写源代码文档。文档注释以斜杠后跟两个星号 (/*), end with an asterisk followed by a backward slash (/) 开头，并且开始和结束之间的所有行必须以星号 (*) 开头。

The documentation comments are used for writing the documentation of the source code. The documentation comments start with a forward slash followed by the two asterisks (/*), end with an asterisk followed by a backward slash (/), and all lines between the start and end must start with an asterisk (*).

Javadoc 工具理解文档注释，并且可用于创建基于 HTML 的文档。

The documentation comments are understood by the Javadoc tool and can be used to create HTML-based documentation.

Syntax

考虑以下语法在 Java 中编写文档注释：

Consider the below syntax to write documentation comment in Java:

/**
* line 1
* line 2
...
*/

Example 1: Java Documentation Comment

/**
 * This is a documentation comment.
 * This is my first Java program.
 * This will print 'Hello World' as the output
 * This is an example of multi-line comments.
*/
public class MyFirstJavaProgram {}

上述注释样式称为文档注释。它由 Javadoc 工具在为程序代码创建文档时使用。我们还可以使用文档注释中的以下注释提供参数、异常和返回类型的详细信息。

The above commenting style is known as documentation comments. It is used by Javadoc tool while creating the documentation for the program code. We can give details of arguments, exception and return type as well using following annotation in documentation comments.

/**
 * @param dividend
 * @param divisor
 * @return quotient
 * @throws IllegalArgumentException if divisor is zero
 */
private double divide(int dividend, int divisor) throws IllegalArgumentException {
}

Example 2: Java Documentation Comment

下述代码显示了在简单程序中使用文档注释。我们已在类声明处定义注释来提供类的详细信息。对于方法，我们正在添加方法注释部分的文档块中的参数、返回值和所引发异常的详细信息。

Following code shows the usage of documentation comments in a simple program. We’ve defined a comments on the class declaration to give details of the class. In case of method, we’re adding details of parameters, return value and exception raised in documentation block of the method comments section.

package com.tutorialspoint;

/**
 * This is a documentation comment.
 * This is my first Java program.
 * This is an example of multi-line comments.
 * We're printing result of divison of two numbers in this program
 */
public class MyFirstJavaProgram {
   public static void main(String[] args) {
     MyFirstJavaProgram program = new MyFirstJavaProgram();
     double result = program.divide(100, 10);
     System.out.println(result);
   }

   /**
    * @param dividend
    * @param divisor
    * @return quotient
    * @throws IllegalArgumentException if divisor is zero
    */
   private double divide(int dividend, int divisor) throws IllegalArgumentException {
      if (divisor == 0) {
         throw new IllegalArgumentException("divisor cannot be zero");
      }
      return (double) dividend / divisor;
   }
}

编译并运行 MyFirstJavaProgram。这将产生以下结果 -

Compile and run MyFirstJavaProgram. This will produce the following result −

10.0