Code Comment Standard

此技能确保代码注释标准化，提升代码可维护性和可读性。

何时应用

在以下场景中必须执行代码注释规范：

1. 创建新的 Java 类文件
2. 定义新的方法（public/protected/private）
3. 创建新的接口
4. 定义复杂的数据结构或 DTO/Entity
5. 定义类的字段/属性
6. 定义枚举类型及其值
7. 编写包含复杂业务逻辑的代码块
8. 修改或重构已有但缺乏注释的代码

注释规范

1. 类级别注释

所有类必须包含 Javadoc 注释，说明：

• 类的功能和职责
• 创建者
• 创建日期

示例：

/**
 * 订单服务类
 * 负责处理订单相关的业务逻辑，包括订单创建、查询、状态更新等功能
 *
 * @author developer
 * @since 2024-01-01
 */
@Service
public class OrderService {
}

2. 方法级别注释

所有方法必须包含 Javadoc 注释，说明：

• 方法功能描述
• @param 参数说明（包括类型、约束、是否为空）
• @return 返回值说明（包括类型、可能的值）
• @throws 异常说明（包括抛出条件和异常类型）

标准方法：

/**
 * 查询指定用户的订单列表
 *
 * @param userId 用户ID，不能为空
 * @param status 订单状态，可选值：1-待支付，2-已支付，3-已完成
 * @param startTime 查询起始时间，格式：yyyy-MM-dd HH:mm:ss
 * @param endTime 查询结束时间，格式：yyyy-MM-dd HH:mm:ss
 * @return 订单列表，按创建时间倒序排列；如果没有数据返回空列表
 * @throws IllegalArgumentException 当 userId 为空或时间格式不正确时抛出
 */
public List<Order> queryUserOrders(Integer userId, Integer status,
                                    String startTime, String endTime) {
}

构造方法：

/**
 * 构造函数
 *
 * @param userId 用户ID
 * @param role 用户角色，不能为空
 */
public UserService(Integer userId, String role) {
}

重载方法： 必须说明与基础方法的区别

/**
 * 查询用户（重载版本：支持分页）
 *
 * @param userId 用户ID
 * @param pageNum 页码，从 1 开始
 * @param pageSize 每页数量，范围 10-100
 * @return 分页结果
 */
public Page<User> queryUsers(Integer userId, int pageNum, int pageSize) {
}

接口方法： 说明实现要求

/**
 * 用户登录接口
 * <p>
 * 实现要求：
 * 1. 密码必须加密传输
 * 2. 失败 3 次锁定账号 30 分钟
 *
 * @param username 用户名
 * @param password 密码（加密后）
 * @return 登录结果
 */
LoginResult login(String username, String password);

3. 字段级别注释

类的字段必须包含注释，说明：

• 字段的含义和用途
• 取值范围或特殊约束（如有）
• 默认值（如有）

方式 1：使用 / / Javadoc 注释（推荐）*

@Getter
@Setter
public class OrderDTO {
    /**
     * 订单编号
     */
    private String orderNo;

    /**
     * 订单创建时间，unix时间戳
     */
    private Long createTime;

    /**
     * 订单状态，固定为order
     */
    private String type;

    /**
     * 支付类型（如 alipay、wechat）
     */
    private String payType;
}

方式 2：使用 JPA @Comment 注解配合

/**
 * 订单状态过滤格式常量
 *
 * 格式说明：
 * - 完整路径格式：/order/{userId}/{status}/{date}/
 * - 示例：/order/1001/paid/2026-01-15/
 */
@Comment("订单状态过滤格式")
public static final String ORDER_STATUS_PATTERN = "/order/%s/%s/%s/";

4. 枚举级别注释

枚举类和枚举值都必须包含注释，说明：

• 枚举类的整体含义
• 每个枚举值的含义和用途
• 对应的数值或业务场景

方式 1：标准枚举（推荐）

/**
 * 订单事件类型枚举
 * <p>
 * 用于标识订单生命周期中的关键事件类型，
 * 主要包括订单创建、支付、发货等事件。
 *
 * @author developer
 * @since 2026-01-15
 */
@Getter
@AllArgsConstructor
public enum OrderEventEnum {

    /**
     * 订单创建事件（用户提交订单时触发）
     */
    ORDER_CREATE("create_order", ""),

    /**
     * 订单支付事件（用户完成支付后触发）
     */
    ORDER_PAY("pay_order", ""),

    /**
     * 订单发货事件（商家发货后触发）
     */
    ORDER_SHIP("ship_order", "");

    /**
     * 事件名称，用于匹配订单回调的 event 字段
     */
    private final String eventName;

    /**
     * 事件值，预留字段
     */
    private final String eventValue;
}

方式 2：简洁版（适用于含义明确的枚举）

/**
 * 用户身份类型枚举
 *
 * @author developer
 * @since 2026-01-01
 */
public enum IdentityType {
    /**
     * 普通用户
     */
    NORMAL_USER(1, "普通用户"),
    /**
     * VIP用户
     */
    VIP_USER(2, "VIP用户"),
    /**
     * 管理员
     */
    ADMIN(3, "管理员");
}

方式 3：复杂枚举（包含多个字段和业务逻辑）

/**
 * 通知模板枚举
 * <p>
 * 定义系统中使用的消息通知模板，
 * 每个模板对应一个特定的业务场景。
 *
 * @author developer
 * @since 2024-03-10
 */
@Getter
@AllArgsConstructor
public enum NotificationEnum {

    /**
     * 订单支付成功通知 - 用于通知用户支付结果
     */
    ORDER_PAY_SUCCESS(1, "order_pay_success", "订单支付成功通知"),

    /**
     * 发货通知 - 用于通知用户商品已发货
     */
    SHIP_NOTIFICATION(2, "ship_notification", "发货通知");

    /**
     * 通知模板ID，唯一标识
     */
    private final Integer id;

    /**
     * 通知模板编码，用于查询数据库
     */
    private final String code;

    /**
     * 通知模板名称，便于人工识别
     */
    private final String name;
}

5. 复杂业务逻辑注释

对于复杂的业务逻辑，使用单行注释（//）说明关键步骤：

public boolean processOrder(OrderDTO orderDTO) throws Exception {
    // ① 验证订单数据是否完整
    if (StringUtils.isBlank(orderDTO.getOrderNo()) || StringUtils.isBlank(orderDTO.getUserId())) {
        return false;
    }

    // ② 检查订单是否已处理，防止重复提交
    if (!checkOrder(orderDTO.getOrderNo(), orderDTO.getUserId())) {
        String orderData = orderDao.selectByOrderNo(orderDTO.getOrderNo(), "source");
        Order order = objectMapper.readValue(orderData, Order.class);
        BeanUtils.copyProperties(orderDTO, order);
        orderDao.insertRecord(order);
        orderService.updateOrderStatus(order);
    }
    return true;
}

算法注释规范：

/**
 * 计算用户权限范围
 * <p>
 * 算法说明：
 * 1. 获取用户的完整权限路径：/user/1001/admin/
 * 2. 使用 LIKE 前缀匹配：permission LIKE '/user/1001/%'
 * 3. 超级管理员（userId=1）可访问所有数据
 *
 * 时间复杂度：O(n)，n 为权限层级数
 * 空间复杂度：O(1)
 *
 * @param userId 用户ID
 * @param roleId 角色ID
 * @return 权限过滤条件（权限路径前缀）
 */
public String buildPermission(Integer userId, Integer roleId) {
}

6. 特殊场景注释

TODO 注释规范：

// 格式：// TODO: [负责人] [任务描述] [优先级]
// TODO: @张三 添加缓存逻辑，优先级 P1

// 格式：// FIXME: [负责人] [问题描述] [影响范围]
// FIXME: @李四 并发情况下可能出现重复提交，影响订单模块

// 要求：
// - 必须标注责任人
// - 描述具体任务而非模糊表达
// - 定期审查并清理已完成的 TODO

废弃方法标记：

/**
 * 旧版用户查询方法
 *
 * @deprecated 已废弃，请使用 {@link #queryUsersV2(Integer, String)}
 * @see #queryUsersV2(Integer, String)
 */
@Deprecated
public List<User> queryUsers(Integer userId) {
}

重大变更说明：

/**
 * 计算用户积分
 * <p>
 * 变更历史：
 * - 2024-01-10: 新增阶梯积分逻辑
 * - 2024-03-15: 修复并发计算错误
 *
 * @param userId 用户ID
 * @return 积分金额
 */
public BigDecimal calculatePoints(Integer userId) {
}

Spring Data JPA 方法：

// 简单方法无需注释（方法名已说明意图）
List<User> findByDeptId(Integer deptId);

// 复杂查询需补充注释
/**
 * 查询指定部门下状态为活跃的用户
 *
 * @param deptId 部门ID
 * @param status 用户状态（1=活跃，2=停用）
 * @return 用户列表
 */
@Query("SELECT u FROM User u WHERE u.deptId = ?1 AND u.status = ?2")
List<User> findActiveUsers(Integer deptId, Integer status);

7. 测试代码注释

测试类：

/**
 * 订单处理策略测试类
 * 使用 Mockito 进行纯单元测试，不加载 Spring 上下文
 *
 * @author developer
 * @since 2024-04-14
 */
public class OrderProcessStrategyTest {
}

测试方法：

/**
 * 测试订单创建事件处理
 *
 * 模拟接收到订单创建事件，验证订单服务正确处理创建流程
 */
@Test
public void testHandleOrderCreateEvent() {
}

8. 注释规范

【强制】规约

1. 类、属性、方法用Javadoc格式/* /
2. 抽象方法必须Javadoc注释：说明功能、参数、返回值、异常
3. 类必须添加创建者和日期
4. 枚举字段必须有注释

【推荐】规约

• 英文不好就用中文注释
• 代码修改同步更新注释
• 删除未使用的字段、方法、参数

【参考】规约

• 谨慎注释代码，无用则删除
• 特殊标记注明人和时间：TODO / FIXME

注释格式规范

注释语言规范

原则：

1. 项目级注释必须统一使用中文
2. 对外公开的 API 可考虑中英双语
3. 技术术语保留英文原文（如 Redis, MQ）

格式规范：

1. 注释首行应该是完整的句子，句末加句号
2. 方法内部注释使用简洁的断语，不加句号
3. 字段注释使用名词短语，不需要主语

示例：

/**
 * 发送系统通知
 * <p>
 * 调用消息服务 API 发送文本消息到指定用户
 *
 * @param userId 接收用户（系统用户ID）
 * @param content 消息内容
 * @throws MessageException 发送失败时抛出
 */
public void sendNotification(String userId, String content) {
}

9. 注释反模式（禁止）

❌ 重复代码逻辑：

// 设置用户名为[用户名]
user.setName("name");  // ← 多余

❌ 过时注释：

// 2023年1月1日修改为返回 10 条
return list;  // ← 实际返回 20 条

❌ 注释掉的代码：

// if (user.isAdmin()) {  // ← 应该删除，不要用注释保留
//     return true;
// }

❌ 情绪化注释：

// 这破代码我也不知道为啥这么写  // ← 不专业
// TODO: 以后有空再优化  // ← 没有明确计划

注释模板

模板 1：标准方法注释

/**
 * [方法功能简述]
 *
 * [方法功能详细描述]
 *
 * @param [参数名] [参数说明]
 * @return [返回值说明]
 * @throws [异常类型] [异常抛出条件]
 */

模板 2：类注释

/**
 * [类名]
 *
 * [类的功能和职责描述]
 *
 * @author [作者]
 * @since [创建日期]
 */

模板 3：字段注释

// 方式 1：Javadoc 注释（推荐）
/**
 * 字段说明
 */
private String fieldName;

// 方式 2：完整 Javadoc（公共 API 或复杂字段）
/**
 * 字段说明
 * <p>
 * 取值范围：...
 * 默认值：...
 */
private String fieldName;

模板 4：枚举注释

/**
 * [枚举类名称]
 * <p>
 * [枚举类整体说明，包括用途和业务场景]
 *
 * @author [作者]
 * @since [创建日期]
 */
public enum EnumName {
    /**
     * [枚举值1说明]
     */
    ENUM_VALUE1(code1, "描述1"),

    /**
     * [枚举值2说明]
     */
    ENUM_VALUE2(code2, "描述2");
}

模板 5：复杂逻辑注释

// [步骤序号] [步骤说明]
// [可选：说明此步骤的目的或原因]

模板 6：TODO 注释

// TODO: [负责人] [任务描述] [优先级]
// FIXME: [负责人] [问题描述] [影响范围]

模板 7：测试类注释

/**
 * [被测试类名]测试类
 *
 * [测试类说明，如使用的测试框架和测试策略]
 *
 * @author [作者]
 * @since [创建日期]
 */
public class [ClassName]Test {
}

模板 8：测试方法注释

/**
 * [测试方法名称]
 *
 * [测试场景描述]
 */
@Test
public void testMethodName() {
}

检查清单

在代码审查时，检查以下要点：

• [ ] 所有 public/protected 方法都有 Javadoc 注释
• [ ] 所有类都有 Javadoc 注释
• [ ] 所有字段都有注释说明其含义和用途
• [ ] 所有枚举类和枚举值都有注释
• [ ] 方法的 @param 包含了所有参数
• [ ] @return 说明了返回值的含义和约束
• [ ] @throws 说明了所有可能抛出的异常
• [ ] 复杂业务逻辑有单行注释说明步骤
• [ ] TODO 注释标注了责任人和具体任务
• [ ] 测试类和方法包含测试场景描述
• [ ] 注释内容与代码逻辑一致
• [ ] 注释使用中文（保持项目语言一致性）
• [ ] 没有过时/无意义/情绪化的注释

注意事项

1. 注释要简洁准确：避免冗长，直接说明"做什么"和"为什么"
2. 注释要随代码更新：修改代码时，必须同步更新注释
3. 避免无意义注释：如 i++; // i加1 这样的注释是多余的
4. 使用正确的格式：
• 类/方法使用 /* /
• 字段使用 /* / 或 //
• 方法内单行注释使用 //，简洁断语不加句号
5. 保持语言一致性：本项目使用中文注释
6. 枚举注释是强制的：每个枚举值和枚举类都必须有注释
7. TODO 必须标注责任人：避免任务遗漏
8. 禁止注释掉代码：使用 Git 历史追踪，不要用注释保留旧代码