Java：注释

1. 单行注释

使用方法

单行注释以 // 开头，注释内容从 // 开始到行尾结束。它们通常用于对单行代码进行简短说明，或者在代码中插入临时注释。

示例

int x = 10; // 定义变量x并赋值为10
// 打印变量x的值
System.out.println(x);

最佳实践

• 使用单行注释来解释复杂或不易理解的代码行。
• 避免冗长的单行注释，保持简洁明了。
• 在代码块前使用单行注释来描述该块的功能。

2. 多行注释

使用方法

多行注释以 /* 开头，以 */ 结束，可以跨越多行。多行注释适用于对较长的代码块进行详细说明，或者用于注释掉大段代码。

示例

/*
  这个方法用于计算两个数的和
  参数：a - 第一个整数
       b - 第二个整数
  返回值：两个整数的和
*/
public int add(int a, int b) {
    return a + b;
}

/* 
  这是一个示例，演示如何注释掉大段代码
public void exampleMethod() {
    // 这里的代码被注释掉了
}
*/

最佳实践

• 使用多行注释对函数、类或复杂的逻辑进行详细解释。
• 避免嵌套多行注释，这会导致代码难以维护。
• 当临时禁用代码段时，可以使用多行注释，但应尽快移除不再需要的注释代码。

3. 文档注释

使用方法

文档注释以 /** 开头，以 */ 结束，通常用于类、接口、方法和字段的声明前。Javadoc工具可以解析这些注释并生成HTML格式的API文档。

常用标签

• @param 用于描述方法的参数。
• @return 用于描述方法的返回值。
• @throws 或 @exception 用于描述方法可能抛出的异常。
• @see 用于提供相关信息的链接。
• @since 表示该元素从哪个版本开始存在。
• @deprecated 标识不推荐使用的元素，并提供替代信息。

示例

/**
 * 这个类表示一个简单的计算器
 *
 * @since 1.0
 */
public class Calculator {

    /**
     * 计算两个整数的和
     *
     * @param a 第一个整数
     * @param b 第二个整数
     * @return 两个整数的和
     * @since 1.0
     */
    public int add(int a, int b) {
        return a + b;
    }

    /**
     * 计算两个整数的差
     *
     * @param a 第一个整数
     * @param b 第二个整数
     * @return 两个整数的差
     * @since 1.0
     */
    public int subtract(int a, int b) {
        return a - b;
    }

    /**
     * 计算两个整数的乘积
     *
     * @param a 第一个整数
     * @param b 第二个整数
     * @return 两个整数的乘积
     * @throws IllegalArgumentException 如果参数为负数
     * @since 1.1
     */
    public int multiply(int a, int b) {
        if (a < 0 || b < 0) {
            throw new IllegalArgumentException("参数不能为负数");
        }
        return a * b;
    }
}

最佳实践

• 使用文档注释为公共API提供详细说明，这有助于自动生成开发文档。
• 描述清楚方法的输入输出和异常情况，以便使用者了解方法的使用方法和注意事项。
• 保持文档注释简洁且有意义，避免冗长和无关的信息。