java-code-comments

何时使用此技能

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

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

触发短语包括：

• “给这段代码添加注释”（为这段代码添加注释）
• “生成 JavaDoc”（生成 JavaDoc）
• “添加类注释”（添加类注释）
• “添加方法注释”（添加方法注释）
• “添加属性注释”（添加字段注释）
• “代码注释”（代码注释）
• “文档注释”（文档注释）
• “一句话给 Java 代码添加注释”（用一句话为 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 Data 仓库）
• 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（异常类）
- [ ] 其他（请 specify）

还要询问注释类型：

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

等待用户确认后再继续下一步。

步骤 3：创建待办列表

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

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

1. 扫描代码库，查找所有匹配的类：

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

2. 针对每个类，确定：

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

3. 按以下格式生成结构化待办列表：

## Todo List: Java Code Comments

### 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）：

   /**
    * [Class description]
    * 
    * <p>This class [purpose and responsibility]
    * 
    * @author [Author name if available]
    * @since [Version or date if available]
    */
   public class UserController {
   

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

   /**
    * <p>[Class description]</p>
    * 
    * <p>This class [purpose and responsibility]</p>
    * 
    * @author [Author name if available]
    * @since [Version or date if available]
    */
   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）：

   /**
    * [Method description]
    * 
    * @param [paramName] [parameter description]
    * @return [return value description]
    * @throws [ExceptionType] [exception description]
    */
   public UserDTO createUser(@RequestBody UserCreateRequest request) {
   

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

   /**
    * <p>[Method description]</p>
    * 
    * <p>[Detailed description]</p>
    * 
    * @param [paramName] [paramType] [parameter description]
    * @return [returnType] [return value description]
    * @exception [full.package.ExceptionType] [exception description]
    */
   public UserDTO createUser(@RequestBody UserCreateRequest request) {
   

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

   /**
    * [Field description]
    */
   private Long userId;
   

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

   /**
    * <p>[Field description]</p>
    * 
    * <p>[Detailed description if needed]</p>
    */
   private Long userId;
   

5. 完成每个类后：

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

进度更新示例：

## Progress Update

✅ Completed: UserController
  - [x] 类注释
  - [x] createUser() - 方法注释
  - [x] updateUser() - 方法注释
  - [x] deleteUser() - 方法注释
  - [x] userId - 属性注释

🔄 In Progress: UserService
  - [x] 类注释
  - [ ] findUserById() - 方法注释
  - [ ] saveUser() - 方法注释

注释质量指南

重要：注释格式标准

此技能遵循两种标准：

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

Java 编码规范要求：

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

类注释应包含：

• 对类用途的清晰描述（遵循 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 - Service 接口注释
• templates/serviceimpl-comment-template.md - Service 实现类注释
• templates/application-service-comment-template.md - Application Service 注释（DDD）
• templates/domain-service-comment-template.md - Domain Service 注释（DDD）
• templates/feign-service-comment-template.md - Feign Service 接口注释
• templates/mapper-comment-template.md - Mapper 注释
• templates/entity-comment-template.md - Entity 类注释
• 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 - Service 注释示例
• examples/entity-example.md - Entity 注释示例
• 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 注释, 代码注解

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本的 API 可能存在差异
2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查功能
3. 环境变量：确保所有必要的环境变量都已正确设置，不要将敏感信息硬编码
4. 依赖冲突：多个版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. 性能陷阱：处理大量数据时注意性能优化，避免 N+1 查询等常见问题