# Java 注释规范

## 概述

当本项目 Java 代码需要新增、调整、审查或统一注释风格时，使用本技能。

完整项目规范文档为 `docs/JAVA_COMMENT_RULES.md`，本技能作为实际执行时的操作清单。

## 类注释模板

类注释统一使用下方模板：

```java
/**
 * @author ${USER}
 * @version 1.0
 * @createTime 2026-04-16
 * @company DUOWEI UNION GROUP CO.,LTD.
 * @description 手动刷新计划含税相关金额
 * @registerPosition dw_saleoutbill_sale
 * @modifier
 * @modifyRecord 2026-04-28 ryan：补充金额刷新逻辑
 */
```

## 类注释字段规则

- `@author`: 优先读取 IDEA 文件模板或项目约定中的 author。修改已有类时，如果类注释中已存在 `@author`，保留原值；如果 IDEA 中无法读取 author，则使用当前系统用户名；仍无法确认时留空等待开发人员补充。
- `@version`: 优先通过 Git 对比 release 中同路径同类文件判断版本。新增类默认 `1.0`；修改已有类且未新增方法时，小版本递增，例如 `1.0` 到 `1.1`；修改已有类且新增方法时，大版本递增，例如 `1.1` 到 `2.0`；Git 或 release 不可用时，按当前改动内容兜底判断。
- `@createTime`: 优先使用类注释或文件上下文中的类创建时间。如果没有类创建时间，则使用当前日期。
- `@company`: 固定写 `DUOWEI UNION GROUP CO.,LTD.`。
- `@description`: 填写类或方法的实际用途。修改已有类或方法时，需要在描述中包含本次修改内容。
- `@registerPosition`: 填写实际模块、服务、路由或业务位置。无法确认时，先根据包名和类名推断；仍无法确认时留空，等待开发人员补充。
- `@modifier`: 修改已有类或方法时填写修改人。优先使用与 `@author` 相同的来源；无法确认时留空等待开发人员补充。
- `@modifyRecord`: 按 `时间 姓名：修改内容` 格式填写修改记录。保留已有记录，并为每次有意义的修改追加新记录。

## Git 对比 release 判断版本

判断是否在 Git 仓库中：

```bash
git rev-parse --is-inside-work-tree
```

查看 release 分支是否存在：

```bash
git branch --all | grep release
```

查看 release tag 是否存在：

```bash
git tag --list | grep release
```

判断 release 中是否存在同路径同类文件：

```bash
git cat-file -e release:src/main/java/com/example/Demo.java
```

查看 release 中的类文件内容：

```bash
git show release:src/main/java/com/example/Demo.java
```

对比当前文件与 release 文件：

```bash
git diff release -- src/main/java/com/example/Demo.java
```

查看方法签名变化时，仍使用文件差异命令，并重点检查新增的 `public`、`private`、`protected` 方法签名：

```bash
git diff release -- src/main/java/com/example/Demo.java
```

如果项目使用 release tag，则将命令中的 `release` 替换为实际 release tag。这里的同类指 release 中同路径、同类名的 Java 文件。新增方法按方法签名判断，字段、注释、import 或已有方法内部逻辑变化不算新增方法。

## 业务代码注释

业务代码每行上方使用一个中文块注释说明该行代码：

```java
/* 判断路由配置是否为空 */
if (!StringUtils.hasText(routeConfigJson)) {
    /* 清空当前动态路由 */
    routeDefinitionRepository.replaceAll(new ArrayList<>());
}
```

不要把块注释放在代码行尾：

```java
if (!StringUtils.hasText(routeConfigJson)) { /* 判断路由配置是否为空 */
    routeDefinitionRepository.replaceAll(new ArrayList<>()); /* 清空当前动态路由 */
}
```

## 空行规则

如果 `/* 内容 */` 是 `{ ... }` 代码块中的第一行，注释直接放在 `{` 下方，中间不加空行。

```java
public void refreshRoutes(String routeConfigJson) {
    /* 判断路由配置是否为空 */
    if (!StringUtils.hasText(routeConfigJson)) {
        /* 清空当前动态路由 */
        routeDefinitionRepository.replaceAll(new ArrayList<>());
    }
}
```

如果 `/* 内容 */` 上方不是以 `{` 结尾的代码块起始行，则注释和上方代码之间保留一个空行。

```java
/* 清空当前动态路由 */
routeDefinitionRepository.replaceAll(new ArrayList<>());

/* 通知Gateway刷新路由缓存 */
routeRefreshPublisher.publishRefreshEvent();
```

## 编辑流程

1. 新增类时，按照类注释模板补齐完整 `/** ... */` 注释。
2. 修改已有类时，保留已有类注释中的创建时间和历史修改记录。
3. 调整 `@version` 前，先使用 Git 命令确认项目是否存在 release 分支或 release tag。
4. 优先对比 release 中同路径同类文件，并检查是否新增方法签名。
5. release 中不存在同路径同类文件时，按新增类处理，版本默认 `1.0`。
6. release 中存在同路径同类文件且未新增方法时，在已有版本号基础上递增小版本。
7. release 中存在同路径同类文件且新增方法时，在已有版本号基础上递增大版本。
8. Git 或 release 不可用时，按当前改动内容兜底判断版本。
9. 修改已有类或方法时，在 `@description` 中补充本次修改内容。
10. 按 `时间 姓名：修改内容` 格式追加 `@modifyRecord`，不要删除历史记录。
11. 将所有行尾 `/* ... */` 注释转换为目标代码上一行的独立中文块注释。
12. 所有新增业务代码注释统一使用中文，说明代码意图，不解释显而易见的语法。
13. 移动或新增注释后，应用本技能中的空行规则。
14. 写入 Java 文件时保持 UTF-8 无 BOM 编码。

## 验证

修改 Java 注释后，执行：

```bash
mvn -q test
```

检查是否仍存在行尾块注释：

```bash
rg -n "\S\s/\*.*\*/\s*$" src/main/java
```

如果 Java 编译报 `非法字符: '\ufeff'`，先将本次改动过的 Java 文件重新保存为 UTF-8 无 BOM，再重新测试。