Java 注释规范

概述

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

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

类注释模板

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

/**
 * @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 仓库中：

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

查看 release 分支是否存在：

git branch --all | grep release

查看 release tag 是否存在：

git tag --list | grep release

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

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

查看 release 中的类文件内容：

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

对比当前文件与 release 文件：

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

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

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

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

业务代码注释

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

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

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

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

空行规则

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

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

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

/* 清空当前动态路由 */
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 注释后，执行：

mvn -q test

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

rg -n "Ss/*.**/s*$" src/main/java

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