注释规范

Java 中有三种注释类型：单行注释、多行注释和文档注释。好的注释让代码更易维护。

注释类型

单行注释

// 开头，行尾结束：

public class Hello {
    public static void main(String[] args) {
        int age = 25;  // 这是单行注释
        System.out.println("Hello");  // 输出语句
    }
}

多行注释

/* ... */ 包裹，可跨越多行：

public class Hello {
    public static void main(String[] args) {
        /*
         * 这是多行注释
         * 可以跨越多行
         * 通常用于较长的说明
         */
        System.out.println("Hello");
    }
}

文档注释

/** ... */ 包裹，会被 Javadoc 工具解析：

/**
 * 这是一个学生类
 *
 * @author Zhang San
 * @version 1.0
 * @since 2024-01-01
 */
public class Student {
    private String name;
    
    /**
     * 获取学生姓名
     *
     * @return 学生的姓名
     */
    public String getName() {
        return name;
    }
}

何时需要注释

场景	示例
公共 API	方法用途、参数说明、返回值
复杂业务逻辑	算法解释、关键判断
重要决策	为什么这样设计
TODO/FIXME	待完成或需要修复的代码

何时不需要注释

• 明显的代码：注释反而干扰阅读
• 更新后的代码：代码本身应自解释
• 误导性注释：过时的注释比没注释更糟糕

注释示例

类注释

/**
 * 用户服务类
 *
 * <p>负责处理用户相关的业务逻辑，包括：
 * <ul>
 *   <li>用户注册和登录</li>
 *   <li>用户信息查询</li>
 *   <li>用户权限管理</li>
 * </ul>
 *
 * @author Developer
 * @version 2.0
 * @see User
 * @see UserRepository
 */
public class UserService {
    // ...
}

方法注释

/**
 * 计算两个整数的和
 *
 * <p>这是一个简单的方法，用于演示文档注释的格式。
 * 方法会返回两个参数的和，如果结果超出 Integer 范围，
 * 则返回 Integer.MAX_VALUE。
 *
 * @param a 第一个整数，不能为 null
 * @param b 第二个整数，不能为 null
 * @return 两个整数的和，如果溢出则返回 Integer.MAX_VALUE
 * @throws IllegalArgumentException 如果 a 或 b 为 null
 *
 * @example
 * <pre>
 * int result = Calculator.add(1, 2);  // result = 3
 * int overflow = Calculator.add(Integer.MAX_VALUE, 1);  // result = Integer.MAX_VALUE
 * </pre>
 */
public static int add(Integer a, Integer b) {
    if (a == null || b == null) {
        throw new IllegalArgumentException("参数不能为 null");
    }
    try {
        return Math.addExact(a, b);
    } catch (ArithmeticException e) {
        return Integer.MAX_VALUE;
    }
}

行内注释

public void processOrder(Order order) {
    // 1. 验证订单有效性
    if (!validateOrder(order)) {
        throw new InvalidOrderException("订单无效");
    }
    
    // 2. 计算订单金额（包含折扣逻辑）
    BigDecimal amount = calculateAmount(order);
    
    // 3. 扣减库存（乐观锁防止超卖）
    inventoryService.reduceStock(order.getItems());
    
    // 4. 发送通知
    notificationService.sendOrderConfirmation(order);
}

注释风格

推荐

// 连接数据库
Connection conn = DriverManager.getConnection(url);

// 使用 Thread.sleep 而不是 wait 是因为不需要锁
Thread.sleep(1000);

// TODO: 优化查询性能
List<User> users = userDao.findAll();

不推荐

// 注释了等于没注释
int i = 0;  // i 加 1

// 错误的注释
int i = 0;  // i 减 1

// 中文和拼音混用
// zhanghao chaxun
User user = userDao.findById(id);

Javadoc 标签

标签	说明	示例
@author	作者	@author Zhang San
@version	版本	@version 1.0
@param	参数	@param name 用户名
@return	返回值	@return 成功与否
@throws	异常	@throws IOException
@see	引用	@see UserService
@since	起始版本	@since 1.0
@deprecated	已废弃	@deprecated 使用新方法

保持注释与代码同步更新，优先写清晰的代码而不是添加注释。