java注释

java注释

注释
为了方便程序的阅读，Java 语言允许程序员在程序中写上一些说明性的文
字，用来提高程序的可读性，这些文字性的说明就称为注释。
注释不会出现在字节码文件中，即 Java 编译器编译时会跳过注释语句。
在 Java 中根据注释的功能不同，主要分为单行注释、多行注释和文档注释。

单行注释

在 Java 中，单行注释是一种注释格式，用于在代码中添加注释或临时禁用代码。单行注释以 // 开头，直到行末结束。单行注释可以用于记录代码的作用、调试信息、临时禁用代码等。

下面是一个使用单行注释的示例：

public class ExampleClass {
    public static void main(String[] args) {
        int x = 10;
        int y = 20;

        // 计算和并打印结果
        int sum = x + y;
        System.out.println("x + y = " + sum);

        // 禁用下面的代码
        // int diff = x - y;
        // System.out.println("x - y = " + diff);
    }
}

在上面的示例中，使用了单行注释来记录代码的作用和临时禁用代码。第 7 行的单行注释描述了计算和的过程，第 10-12 行的单行注释禁用了计算差的代码。

使用单行注释时，需要注意以下几点：

• 单行注释只能注释当前行的代码，不能跨行注释。
• 单行注释可以出现在任何合法的代码位置，包括语句前、语句后、表达式中等。
• 单行注释不会被编译器编译，不会影响程序的运行效果。
• 单行注释应该清晰明了地说明代码的作用，避免使用无意义的注释或注释与代码不符的情况。

多行注释

在 Java 中，多行注释是一种注释格式，用于在代码中添加注释或临时禁用多行代码。多行注释以 /* 开头，以 */ 结束，可以跨越多行。多行注释可以用于记录代码的作用、调试信息、临时禁用代码等。

下面是一个使用多行注释的示例：

public class ExampleClass {
    public static void main(String[] args) {
        int x = 10;
        int y = 20;

        /*
         * 计算和并打印结果
         */
        int sum = x + y;
        System.out.println("x + y = " + sum);

        /*
         * 禁用下面的代码
         *
         * int diff = x - y;
         * System.out.println("x - y = " + diff);
         */
    }
}

在上面的示例中，使用了多行注释来记录代码的作用和临时禁用多行代码。第 7-9 行的多行注释描述了计算和的过程，第 12-18 行的多行注释禁用了计算差的代码。

使用多行注释时，需要注意以下几点：

• 多行注释可以跨越多行，但不能嵌套使用。
• 多行注释不会被编译器编译，不会影响程序的运行效果。
• 多行注释应该清晰明了地说明代码的作用，避免使用无意义的注释或注释与代码不符的情况。
• 在多行注释中可以使用单行注释，但不能使用多行注释。

文档注释

在 Java 中，文档注释是一种特殊的注释格式，用于为类、接口、方法和字段等元素提供详细的文档说明。文档注释以 /** 开始，以 */ 结束，位于被注释元素的前面。

Java 的文档注释使用一种称为 Javadoc 的标记语言来编写。Javadoc 标记由 @ 符号开头，后跟标记名称和相应的描述信息。这些标记可以用于记录参数、返回值、异常、作者、版本号等元素的信息，以及提供对类、方法和字段等的描述、示例代码等内容。

下面是一个使用文档注释的示例：

/**
 * 这是一个示例类，用于演示文档注释的使用。
 *
 * @author Binjie
 * @version 1.0
 */
public class ExampleClass {

    /**
     * 这是一个示例方法，用于演示文档注释的使用。
     *
     * @param name 名字
     * @return 拼接后的字符串
     * @throws IllegalArgumentException 如果名字为空，则抛出此异常
     */
    public String sayHello(String name) throws IllegalArgumentException {
        if (name == null || name.isEmpty()) {
            throw new IllegalArgumentException("名字不能为空");
        }
        return "Hello, " + name + "!";
    }
}

在上面的示例中，类 ExampleClass 和方法 sayHello 都使用了文档注释。@author 标记用于指定作者，@version 标记用于指定版本号。方法 sayHello 的文档注释中使用了 @param 标记来描述参数，@return 标记来描述返回值，@throws 标记来描述可能抛出的异常。

使用文档注释时，可以通过 Javadoc 工具生成相应的 HTML 文档，并提供给其他开发人员查阅。这样可以帮助其他人理解你的代码、使用你的类和方法，并减少开发过程中的沟通成本。要生成 Javadoc 文档，可以使用以下命令：

javadoc ExampleClass.java

执行上述命令后，会在当前目录下生成一个名为 index.html 的文件，其中包含了生成的文档内容。