Java 注释规范助手

要解决的问题

• 类注释：@author、@version、@company、@description 等字段常出现格式不一、来源不明，新增和修改时尤其容易互相覆盖。
• 业务注释：行尾 /* ... */、中英文混用、注释与代码之间的空行不一致，会影响阅读和审查。
• 版本字段：新增或修改时难以判断应写 1.0、1.1 还是 2.0，容易产生虚假版本号。
• 文件编码：BOM 可能导致 Java 编译报 非法字符: '\ufeff'。

技能如何工作

本技能把 docs/JAVA_COMMENT_RULES.md 转成可执行清单：

1. 新增类时补齐完整 /** ... */ 注释，并按模板填写字段。
2. 修改已有类时保留 @createTime 与历史 @modifyRecord，在 @description 中补充本次修改。
3. 调整 @version 前，先检查 Git 是否存在 release 分支或 release tag，再对比同路径同类文件；不存在按新增类写 1.0，存在且未新增方法递增小版本，存在且新增方法签名递增大版本。
4. 业务代码统一使用中文块注释，放在目标代码上一行，不放在行尾。
5. 按空行规则处理：若注释是 { ... } 块内第一行，直接放在 { 下方；否则与上方代码保留一个空行。
6. 写入后保持 UTF-8 无 BOM，并检查是否仍残留行尾块注释。

适用边界与注意点

• 适用于 Java 注释新增、调整、审查和统一风格，不替代完整项目规范文档。
• @author、@registerPosition、@modifier 无法确认时应留空或按上下文推断，避免编造责任人。
• @version 依赖 Git/release 信息；不可用时只能按当前改动兜底判断。
• 新增方法按方法签名判断；字段、import、注释或已有方法内部逻辑变化不算新增方法。