# Java 代码注释规范

> 本文件定义 MES 项目 Java 代码的注释规范，在代码生成阶段由 AI 读取并遵循。

## 类级别注释

- 所有类（Entity、Controller、Service、ServiceImpl、Mapper、测试类等）必须使用 JavaDoc 格式注释
- 必须包含：功能描述、@author、@date
- 格式：
  ```java
  /**
   * 物料主数据实体类
   *
   * @author AI-Generated
   * @date 2025-01-01
   */
  ```

## 方法级别注释

- 公共方法（public）必须使用 JavaDoc 格式，包含功能描述、@param、@return、@throws（如有）
- 私有方法（private）使用行内 `//` 注释说明意图
- 接口方法必须写 JavaDoc（作为契约文档）
- 重写方法（@Override）如果父类已有 JavaDoc，可用 `//` 补充差异说明
- 格式：
  ```java
  /**
   * 分页查询物料列表
   *
   * @param page 分页参数
   * @param entity 查询条件
   * @return 分页结果
   */
  IPage<MmMaterial> pageSearch(Page<MmMaterial> page, @Param("entity") MmMaterial entity);
  ```

## 字段级别注释

- Entity 业务字段使用 `//` 行内注释标注业务含义（与 @ExcelProperty 配合）
- 常量（static final）使用 JavaDoc 格式
- 集合字段注释说明子表含义
- 字段注释必须写在字段上方独立一行，禁止写在行尾
- 格式：
  ```java
  // 物料编码，唯一标识
  @ExcelProperty("物料编码")
  private String materialCode;

  /** 批次大小，默认 500 */
  public static final int DEFAULT_BATCH_SIZE = 500;
  ```

## 行内注释

- 复杂业务逻辑必须添加行内注释说明意图
- Service 层校验逻辑必须注释说明校验规则
- 行内注释必须写在代码上方独立一行，禁止写在行尾
- 禁止无意义注释（如 `// 设置名称` 紧跟 `entity.setName()`）
- 格式：
  ```java
  // 校验物料编码唯一性（按组织维度）
  LambdaQueryWrapper<MmMaterial> wrapper = new LambdaQueryWrapper<>();
  wrapper.eq(MmMaterial::getMaterialCode, code);

  // 批量查询后内存处理，避免 N+1
  List<MmMaterial> existing = this.list(wrapper);
  ```

## 特殊场景

- Controller 方法：简要 JavaDoc 说明接口用途，参数说明可省略（框架自动解析）
- Service 事务方法：JavaDoc 说明业务逻辑和异常场景
- 测试方法：JavaDoc 或 @DisplayName 说明测试场景，无需 @param/@return
- Mapper XML：`<!-- 注释 -->` 说明 SQL 片段用途
- 枚举类：每个枚举值使用 `//` 注释说明含义