Java代码注释技能Skill java-code-comments

---

name: java-code-comments description: | 提供Java代码注释的全面指导，遵循行业标准和最佳实践。 此技能帮助为Java代码添加类级注释、方法级注释和字段级注释。 当用户想为Java代码添加注释、需要记录Java类/方法/字段、 希望改进代码文档或需要生成JavaDoc注释时使用。此技能覆盖Controller、 Service、ServiceImpl、Mapper、Model、Entity、BO（业务对象）、DTO、VO和其他常见Java 组件类型。该技能遵循系统化工作流程：扫描代码库、识别组件、创建待办列表，并按顺序添加注释（类注释 → 方法注释 → 字段注释）。 license: 完整条款见LICENSE.txt

何时使用此技能

当用户提到以下内容时，始终使用此技能：

• 为Java代码添加注释
• 记录Java类、方法或字段
• 生成JavaDoc注释
• 改进代码文档
• 代码注解或代码注释
• 给 Java 代码添加注释
• 生成 Java 文档注释
• 代码注释
• 添加注释

触发短语包括：

• “给这段代码添加注释”
• “生成 JavaDoc”
• “添加类注释”
• “添加方法注释”
• “添加属性注释”
• “代码注释”
• “文档注释”
• “一句话给 Java 代码添加注释”

此技能处理的组件类型：

• Controller（REST控制器，Spring MVC控制器）
• Service（业务服务接口）
• ServiceImpl（服务实现）
• Application Service（DDD应用服务，编排领域逻辑）
• Domain Service（DDD领域服务，领域业务逻辑）
• Feign Service Interface（Feign远程服务接口）
• Mapper（MyBatis映射器，数据访问层）
• Model（数据模型，领域模型）
• Entity（JPA实体，数据库实体）
• BO（业务对象，业务逻辑对象）
• DTO（数据传输对象）
• VO（值对象，视图对象）
• DAO（数据访问对象）
• Repository（Spring数据仓库）
• Configuration（Spring配置类）
• Component（Spring组件）
• Utility（工具类）
• Exception（自定义异常类）

如何使用此技能

关键：当用户想为Java代码添加注释时，无论组件类型或复杂度如何，都应触发此技能。

工作流程概述

此技能遵循系统化的4步工作流程：

1. 扫描和理解 - 扫描整个代码库和相关文档以获得全面理解
2. 确认组件类型 - 询问用户确认需要注释的组件类型
3. 创建待办列表 - 生成详细的待办列表，包含类名和方法名
4. 执行注释工作 - 按顺序添加注释：类注释 → 方法注释 → 字段注释，每次完成后更新待办列表

逐步过程

步骤1：扫描和理解代码库

关键：在添加任何注释之前，您必须：

1. 扫描所有Java文件 在项目中：

   • 读取当前目录和子目录中的所有 .java 文件
   • 理解项目结构和架构
   • 识别类之间的关系（依赖、继承、组合）

2. 阅读相关文档：

   • README.md 文件
   • API文档
   • 架构文档
   • 业务需求文档（如果可用）

3. 理解上下文：

   • 每个类是做什么的？
   • 每个方法的目的是什么？
   • 字段代表什么？
   • 组件如何相互交互？

4. 识别模式：

   • 项目中使用的命名约定
   • 现有的注释风格（如果有）
   • 架构模式（MVC、DDD等）
   • 框架使用（Spring、MyBatis等）

输出：您对代码库理解的摘要，包括：

• 项目结构概述
• 识别出的关键组件
• 检测到的架构模式
• 现有文档状态

步骤2：确认组件类型

关键：您必须询问用户确认需要注释的组件类型。

呈现常见Java组件类型的复选框，并请用户选择：

请确认需要进行代码注释的分类（可多选）：
- [ ] Controller（控制器）
- [ ] Service（服务接口）
- [ ] ServiceImpl（服务实现）
- [ ] Application Service（应用服务，DDD架构）
- [ ] Domain Service（领域服务，DDD架构）
- [ ] Feign Service Interface（Feign远程服务接口）
- [ ] Mapper（数据访问层）
- [ ] Model（数据模型）
- [ ] Entity（实体类）
- [ ] BO（业务对象）
- [ ] DTO（数据传输对象）
- [ ] VO（视图对象）
- [ ] DAO（数据访问对象）
- [ ] Repository（仓储）
- [ ] Configuration（配置类）
- [ ] Component（组件类）
- [ ] Utility（工具类）
- [ ] Exception（异常类）
- [ ] 其他（请指定）

同时询问注释类型：

• [ ] 类注释（类级注释）
• [ ] 方法注释（方法级注释）
• [ ] 属性注释（字段级注释）

在继续下一步之前，等待用户确认。

步骤3：创建待办列表

关键：用户确认组件类型后，创建详细的待办列表。

对于用户选择的每个组件类型：

1. 扫描代码库 以找到所有匹配的类：

   • 使用文件搜索查找匹配模式的类（例如，*Controller.java，*Service.java）
   • 列出所有需要注释的类

2. 对于每个类，识别：

   • 类名
   • 需要注释的方法
   • 需要注释的字段

3. 生成结构化的待办列表，格式如下：

## 待办列表：Java代码注释

### Controller 层
- [ ] UserController
  - [ ] 类注释
  - [ ] createUser() - 方法注释
  - [ ] updateUser() - 方法注释
  - [ ] deleteUser() - 方法注释
  - [ ] userId - 属性注释

### Service 层
- [ ] UserService
  - [ ] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

### ServiceImpl 层
- [ ] UserServiceImpl
  - [ ] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

### Mapper 层
- [ ] UserMapper
  - [ ] 类注释
  - [ ] selectById() - 方法注释

### Model/Entity 层
- [ ] User
  - [ ] 类注释
  - [ ] id - 属性注释
  - [ ] username - 属性注释
  - [ ] email - 属性注释

重要：

• 按组件类型组织
• 列出所有匹配所选类型的类
• 包括所有需要注释的方法和字段
• 使用复选框跟踪进度

步骤4：执行注释工作

关键：按指定顺序添加注释，并在每次完成后更新待办列表。

执行顺序：

1. 类级注释 - 首先
2. 方法级注释 - 其次
3. 字段级注释 - 第三

对于待办列表中的每个项目：

1. 一次处理一个类：

   • 从类级注释开始
   • 然后处理该类中的所有方法
   • 最后处理该类中的所有字段
   • 完成每个类后更新待办列表

2. 类级注释格式（标准JavaDoc）：

   /**
    * [类描述]
    * 
    * <p>这个类 [目的和职责]
    * 
    * @author [作者名，如果可用]
    * @since [版本或日期，如果可用]
    */
   public class UserController {
   

   类级注释格式（Java编码规范 - 严格）：

   /**
    * <p>[类描述]</p>
    * 
    * <p>这个类 [目的和职责]</p>
    * 
    * @author [作者名，如果可用]
    * @since [版本或日期，如果可用]
    */
   public class UserController {
   

   专门的类注释格式（Java编码规范 - 严格）：

   应用服务：

   /**
    * {服务名称}应用服务
    *
    * <p>{详细描述服务的业务功能、职责和应用场景}</p>
    * <p>主要功能包括:</p>
    * <ul>
    *   <li>{功能点1}</li>
    *   <li>{功能点2}</li>
    *   <li>{功能点3}</li>
    * </ul>
    *
    * @author system
    * @since 2025-01-21
    */
   public class UserApplicationService {
   

   领域服务：

   /**
    * {服务名称}领域服务
    *
    * <p>{详细描述服务的领域职责和业务逻辑}</p>
    * <p>主要功能包括:</p>
    * <ul>
    *   <li>{功能点1}</li>
    *   <li>{功能点2}</li>
    * </ul>
    *
    * @author system
    * @since 2025-01-21
    */
   public class UserDomainService {
   

   Feign服务接口：

   /**
    * {服务名称}Feign远程服务接口
    *
    * <p>通过Feign调用{目标服务}的远程接口</p>
    * <p>主要功能:</p>
    * <ul>
    *   <li>{接口功能1}</li>
    *   <li>{接口功能2}</li>
    * </ul>
    *
    * @author system
    * @since 2025-01-21
    */
   public interface UserFeignService {
   

3. 方法级注释格式（标准JavaDoc）：

   /**
    * [方法描述]
    * 
    * @param [参数名] [参数描述]
    * @return [返回值描述]
    * @throws [异常类型] [异常描述]
    */
   public UserDTO createUser(@RequestBody UserCreateRequest request) {
   

   方法级注释格式（Java编码规范 - 严格）：

   /**
    * <p>[方法描述]</p>
    * 
    * <p>[详细描述]</p>
    * 
    * @param [参数名] [参数类型] [参数描述]
    * @return [返回类型] [返回值描述]
    * @exception [完整包名.异常类型] [异常描述]
    */
   public UserDTO createUser(@RequestBody UserCreateRequest request) {
   

4. 字段级注释格式（标准JavaDoc）：

   /**
    * [字段描述]
    */
   private Long userId;
   

   字段级注释格式（Java编码规范 - 严格）：

   /**
    * <p>[字段描述]</p>
    * 
    * <p>[如果需要，详细描述]</p>
    */
   private Long userId;
   

5. 完成每个类后：

   • 更新待办列表：用 [x] 标记已完成项目
   • 向用户显示进度
   • 继续下一个类

进度更新示例：

## 进度更新

✅ 已完成：UserController
  - [x] 类注释
  - [x] createUser() - 方法注释
  - [x] updateUser() - 方法注释
  - [x] deleteUser() - 方法注释
  - [x] userId - 属性注释

🔄 进行中：UserService
  - [x] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

注释质量指南

重要：注释格式标准

此技能遵循两种标准：

1. 标准JavaDoc（默认）：参见 javadoc-standards.md（在此技能内）
2. Java编码规范（严格）：参见 java-coding-standards.md（在此技能内）

Java编码规范要求：

• 描述必须包裹在 <p> 标签中：<p>描述</p>
• 参数类型必须声明：@param 参数名 参数类型 描述
• 返回类型必须声明：@return 返回类型 描述
• 异常类型必须声明完整包名：@exception java.lang.Exception 描述

类注释应包括：

• 类目的的清晰描述（如果遵循Java编码规范，包裹在 <p> 标签中）
• 主要职责
• 使用示例（如果复杂）
• 相关类或组件
• 作者和版本（如果可用）

方法注释应包括：

• 方法做什么的清晰描述（如果遵循Java编码规范，包裹在 <p> 标签中）
• 所有参数及其描述和类型
• 返回值描述及其类型
• 可能抛出的异常（带有完整包名）
• 使用示例（对于复杂方法）
• 副作用（如果有）

字段注释应包括：

• 字段代表的清晰描述（如果遵循Java编码规范，包裹在 <p> 标签中）
• 数据类型和约束（如果适用）
• 默认值（如果适用）
• 与其他字段的关系（如果适用）

最佳实践

1. 简洁但完整：注释应清晰信息丰富，但不冗长
2. 使用JavaDoc格式：遵循标准JavaDoc约定
3. 保持一致：在所有注释中使用一致的风格
4. 更新待办列表：每次完成后始终更新待办列表
5. 一次处理一个类：在处理下一个类之前完成一个完整的类
6. 尊重现有代码：不要修改代码逻辑，只添加注释
7. 上下文感知：注释应反映实际代码行为和业务上下文

注释模板

对于不同的组件类型，使用 templates/ 目录中的适当模板：

• templates/controller-comment-template.md - Controller类注释
• templates/service-comment-template.md - 服务接口注释
• templates/serviceimpl-comment-template.md - 服务实现注释
• templates/application-service-comment-template.md - 应用服务注释（DDD）
• templates/domain-service-comment-template.md - 领域服务注释（DDD）
• templates/feign-service-comment-template.md - Feign服务接口注释
• templates/mapper-comment-template.md - Mapper注释
• templates/entity-comment-template.md - 实体类注释
• templates/dto-comment-template.md - DTO类注释

注释标准参考

注意：所有参考文档位于此技能目录结构中。

• 标准JavaDoc：参见 reference/javadoc-standards.md（本地参考）
• Java编码规范（严格格式）：参见 reference/java-coding-standards.md（本地参考）

何时使用Java编码规范格式：

• 当项目明确遵循《JAVA 编程规范》时
• 当项目要求严格格式，描述用 <p> 标签时
• 当注释中必须明确声明参数和返回类型时

示例

参见 examples/ 目录以获取完整示例：

• examples/controller-example.md - Controller注释示例
• examples/service-example.md - 服务注释示例
• examples/entity-example.md - 实体注释示例
• examples/full-workflow-example.md - 完整工作流程示例

关键词

英文关键词： java, code comments, javadoc, documentation, class comments, method comments, field comments, code annotation, code documentation, java documentation, add comments, generate comments, document code, code comments java, java code comments, controller comments, service comments, mapper comments, entity comments, dto comments

中文关键词（中文关键词）： Java 代码注释, 添加注释, 生成注释, 代码注释, 文档注释, JavaDoc, 类注释, 方法注释, 属性注释, 字段注释, 给代码添加注释, 代码文档, Java 文档, 注释生成, 一句话添加注释, Controller 注释, Service 注释, Mapper 注释, Entity 注释, DTO 注释, 代码注解