java-code-comments
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWhen to use this skill
何时使用本技能
ALWAYS use this skill when the user mentions:
- Adding comments to Java code
- Documenting Java classes, methods, or fields
- Generating JavaDoc comments
- Improving code documentation
- Code annotation or code commenting
- 给 Java 代码添加注释
- 生成 Java 文档注释
- 代码注释
- 添加注释
Trigger phrases include:
- "给这段代码添加注释" (add comments to this code)
- "生成 JavaDoc" (generate JavaDoc)
- "添加类注释" (add class comments)
- "添加方法注释" (add method comments)
- "添加属性注释" (add field comments)
- "代码注释" (code comments)
- "文档注释" (documentation comments)
- "一句话给 Java 代码添加注释" (add comments to Java code with one sentence)
Component types this skill handles:
- Controller (REST controllers, Spring MVC controllers)
- Service (business service interfaces)
- ServiceImpl (service implementations)
- Application Service (DDD application services, orchestrating domain logic)
- Domain Service (DDD domain services, domain business logic)
- Feign Service Interface (Feign remote service interfaces)
- Mapper (MyBatis mappers, data access layer)
- Model (data models, domain models)
- Entity (JPA entities, database entities)
- BO (Business Object, business logic objects)
- DTO (Data Transfer Object)
- VO (Value Object, View Object)
- DAO (Data Access Object)
- Repository (Spring Data repositories)
- Configuration (Spring configuration classes)
- Component (Spring components)
- Utility (utility classes)
- Exception (custom exception classes)
当用户提及以下内容时,请务必使用本技能:
- 为Java代码添加注释
- 对Java类、方法或字段进行文档化
- 生成JavaDoc注释
- 提升代码文档质量
- 代码注解或代码注释
- 给 Java 代码添加注释
- 生成 Java 文档注释
- 代码注释
- 添加注释
触发短语包括:
- "给这段代码添加注释" (add comments to this code)
- "生成 JavaDoc" (generate JavaDoc)
- "添加类注释" (add class comments)
- "添加方法注释" (add method comments)
- "添加属性注释" (add field comments)
- "代码注释" (code comments)
- "文档注释" (documentation comments)
- "一句话给 Java 代码添加注释" (add comments to Java code with one sentence)
本技能支持的组件类型:
- Controller(REST控制器、Spring MVC控制器)
- Service(业务服务接口)
- ServiceImpl(服务实现类)
- Application Service(DDD应用服务,编排领域逻辑)
- Domain Service(DDD领域服务,处理领域业务逻辑)
- Feign Service Interface(Feign远程服务接口)
- Mapper(MyBatis映射器,数据访问层)
- Model(数据模型、领域模型)
- Entity(JPA实体类、数据库实体)
- BO(Business Object,业务逻辑对象)
- DTO(Data Transfer Object,数据传输对象)
- VO(Value Object,视图对象)
- DAO(Data Access Object,数据访问对象)
- Repository(Spring Data仓储)
- Configuration(Spring配置类)
- Component(Spring组件类)
- Utility(工具类)
- Exception(自定义异常类)
How to use this skill
如何使用本技能
CRITICAL: This skill should be triggered when the user wants to add comments to Java code, regardless of the component type or complexity.
重要提示:当用户需要为Java代码添加注释时,无论组件类型或复杂度如何,都应触发本技能。
Workflow Overview
工作流概述
This skill follows a systematic 4-step workflow:
- Scan and Understand - Scan the entire codebase and related documentation to gain comprehensive understanding
- Confirm Component Types - Ask user to confirm which component types need comments
- Create Todo List - Generate a detailed todo list with class names and method names
- Execute Commenting - Add comments in order: class comments → method comments → field comments, updating todo list after each completion
本技能遵循系统化的四步工作流:
- 扫描与理解 - 扫描整个代码库及相关文档,全面理解项目
- 确认组件类型 - 请用户确认需要添加注释的组件类型
- 创建待办事项列表 - 生成包含类名和方法名的详细待办列表
- 执行注释添加 - 按顺序添加注释:类注释 → 方法注释 → 字段注释,完成每项后更新待办列表
Step-by-Step Process
分步流程
Step 1: Scan and Understand the Codebase
步骤1:扫描与理解代码库
CRITICAL: Before adding any comments, you MUST:
-
Scan all Java files in the project:
- Read all files in the current directory and subdirectories
.java - Understand the project structure and architecture
- Identify relationships between classes (dependencies, inheritance, composition)
- Read all
-
Read related documentation:
- README.md files
- API documentation
- Architecture documentation
- Business requirements documents (if available)
-
Understand the context:
- What does each class do?
- What is the purpose of each method?
- What do fields represent?
- How do components interact with each other?
-
Identify patterns:
- Naming conventions used in the project
- Existing comment styles (if any)
- Architecture patterns (MVC, DDD, etc.)
- Framework usage (Spring, MyBatis, etc.)
Output: A summary of your understanding of the codebase, including:
- Project structure overview
- Key components identified
- Architecture patterns detected
- Existing documentation status
重要提示:在添加任何注释之前,您必须完成以下操作:
-
扫描项目中所有Java文件:
- 读取当前目录及子目录下的所有文件
.java - 理解项目结构与架构
- 识别类之间的关系(依赖、继承、组合)
- 读取当前目录及子目录下的所有
-
阅读相关文档:
- README.md文件
- API文档
- 架构文档
- 业务需求文档(如有)
-
理解上下文:
- 每个类的作用是什么?
- 每个方法的用途是什么?
- 每个字段代表什么?
- 组件之间如何交互?
-
识别模式:
- 项目中使用的命名规范
- 现有注释风格(如有)
- 架构模式(MVC、DDD等)
- 框架使用情况(Spring、MyBatis等)
输出:代码库理解总结,包括:
- 项目结构概述
- 识别出的关键组件
- 检测到的架构模式
- 现有文档状态
Step 2: Confirm Component Types
步骤2:确认组件类型
CRITICAL: You MUST ask the user to confirm which component types need comments.
Present a checklist of common Java component types and ask the user to select:
请确认需要进行代码注释的分类(可多选):
- [ ] 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)Also ask about comment types:
- 类注释(Class-level comments)
- 方法注释(Method-level comments)
- 属性注释(Field-level comments)
Wait for user confirmation before proceeding to the next step.
重要提示:您必须请用户确认需要添加注释的组件类型。
向用户展示常见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)同时询问注释类型:
- 类注释(Class-level comments)
- 方法注释(Method-level comments)
- 属性注释(Field-level comments)
等待用户确认后,再进行下一步。
Step 3: Create Todo List
步骤3:创建待办事项列表
CRITICAL: After user confirms component types, create a detailed todo list.
For each component type selected by the user:
-
Scan the codebase to find all matching classes:
- Use file search to find classes matching the pattern (e.g., ,
*Controller.java)*Service.java - List all classes that need comments
- Use file search to find classes matching the pattern (e.g.,
-
For each class, identify:
- Class name
- Methods that need comments
- Fields that need comments
-
Generate a structured todo list in the following format:
markdown
undefined重要提示:用户确认组件类型后,创建详细的待办事项列表。
针对用户选择的每种组件类型:
-
扫描代码库找到所有匹配的类:
- 使用文件搜索找到符合模式的类(例如、
*Controller.java)*Service.java - 列出所有需要添加注释的类
- 使用文件搜索找到符合模式的类(例如
-
针对每个类,识别:
- 类名
- 需要添加注释的方法
- 需要添加注释的字段
-
生成结构化待办列表,格式如下:
markdown
undefinedTodo List: Java Code Comments
Todo List: Java Code Comments
Controller 层
Controller 层
- UserController
- 类注释
- createUser() - 方法注释
- updateUser() - 方法注释
- deleteUser() - 方法注释
- userId - 属性注释
- UserController
- 类注释
- createUser() - 方法注释
- updateUser() - 方法注释
- deleteUser() - 方法注释
- userId - 属性注释
Service 层
Service 层
- UserService
- 类注释
- findUserById() - 方法注释
- saveUser() - 方法注释
- UserService
- 类注释
- findUserById() - 方法注释
- saveUser() - 方法注释
ServiceImpl 层
ServiceImpl 层
- UserServiceImpl
- 类注释
- findUserById() - 方法注释
- saveUser() - 方法注释
- UserServiceImpl
- 类注释
- findUserById() - 方法注释
- saveUser() - 方法注释
Mapper 层
Mapper 层
- UserMapper
- 类注释
- selectById() - 方法注释
- UserMapper
- 类注释
- selectById() - 方法注释
Model/Entity 层
Model/Entity 层
- User
- 类注释
- id - 属性注释
- username - 属性注释
- email - 属性注释
**Important**:
- Organize by component type
- List all classes that match the selected types
- Include all methods and fields that need comments
- Use checkboxes for tracking progress- User
- 类注释
- id - 属性注释
- username - 属性注释
- email - 属性注释
**注意事项**:
- 按组件类型组织
- 列出所有匹配所选类型的类
- 包含所有需要添加注释的方法和字段
- 使用复选框跟踪进度Step 4: Execute Commenting Work
步骤4:执行注释添加工作
CRITICAL: Add comments in the specified order and update todo list after each completion.
Order of execution:
- Class-level comments (类注释) - First
- Method-level comments (方法注释) - Second
- Field-level comments (属性注释) - Third
For each item in the todo list:
-
Process one class at a time:
- Start with class-level comment
- Then process all methods in that class
- Finally process all fields in that class
- Update the todo list after completing each class
-
Class-level comment format (Standard JavaDoc):java
/** * [Class description] * * <p>This class [purpose and responsibility] * * @author [Author name if available] * @since [Version or date if available] */ public class UserController {Class-level comment format (Java Coding Standards - strict):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 {Specialized class comment formats (Java Coding Standards - strict):Application Service: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 {Domain Service:java/** * {服务名称}领域服务 * * <p>{详细描述服务的领域职责和业务逻辑}</p> * <p>主要功能包括:</p> * <ul> * <li>{功能点1}</li> * <li>{功能点2}</li> * </ul> * * @author system * @since 2025-01-21 */ public class UserDomainService {Feign Service Interface:java/** * {服务名称}Feign远程服务接口 * * <p>通过Feign调用{目标服务}的远程接口</p> * <p>主要功能:</p> * <ul> * <li>{接口功能1}</li> * <li>{接口功能2}</li> * </ul> * * @author system * @since 2025-01-21 */ public interface UserFeignService { -
Method-level comment format (Standard JavaDoc):java
/** * [Method description] * * @param [paramName] [parameter description] * @return [return value description] * @throws [ExceptionType] [exception description] */ public UserDTO createUser(@RequestBody UserCreateRequest request) {Method-level comment format (Java Coding Standards - strict):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) { -
Field-level comment format (Standard JavaDoc):java
/** * [Field description] */ private Long userId;Field-level comment format (Java Coding Standards - strict):java/** * <p>[Field description]</p> * * <p>[Detailed description if needed]</p> */ private Long userId; -
After completing each class:
- Update the todo list: mark completed items with
[x] - Show progress to the user
- Continue to the next class
- Update the todo list: mark completed items with
Example progress update:
markdown
undefined重要提示:按指定顺序添加注释,完成每项后更新待办列表。
执行顺序:
- 类级注释 (类注释) - 优先处理
- 方法级注释 (方法注释) - 其次处理
- 字段级注释 (属性注释) - 最后处理
针对待办列表中的每一项:
-
一次处理一个类:
- 先添加类级注释
- 然后处理该类的所有方法
- 最后处理该类的所有字段
- 完成每个类后更新待办列表
-
类级注释格式(标准JavaDoc):java
/** * [Class description] * * <p>This class [purpose and responsibility] * * @author [Author name if available] * @since [Version or date if available] */ public class UserController {类级注释格式(严格遵循Java编码规范):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编码规范):Application Service: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 {Domain Service:java/** * {服务名称}领域服务 * * <p>{详细描述服务的领域职责和业务逻辑}</p> * <p>主要功能包括:</p> * <ul> * <li>{功能点1}</li> * <li>{功能点2}</li> * </ul> * * @author system * @since 2025-01-21 */ public class UserDomainService {Feign Service Interface:java/** * {服务名称}Feign远程服务接口 * * <p>通过Feign调用{目标服务}的远程接口</p> * <p>主要功能:</p> * <ul> * <li>{接口功能1}</li> * <li>{接口功能2}</li> * </ul> * * @author system * @since 2025-01-21 */ public interface UserFeignService { -
方法级注释格式(标准JavaDoc):java
/** * [Method description] * * @param [paramName] [parameter description] * @return [return value description] * @throws [ExceptionType] [exception description] */ public UserDTO createUser(@RequestBody UserCreateRequest request) {方法级注释格式(严格遵循Java编码规范):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) { -
字段级注释格式(标准JavaDoc):java
/** * [Field description] */ private Long userId;字段级注释格式(严格遵循Java编码规范):java/** * <p>[Field description]</p> * * <p>[Detailed description if needed]</p> */ private Long userId; -
完成每个类后:
- 更新待办列表:用标记已完成项
[x] - 向用户展示进度
- 继续处理下一个类
- 更新待办列表:用
进度更新示例:
markdown
undefinedProgress Update
Progress Update
✅ Completed: UserController
- 类注释
- createUser() - 方法注释
- updateUser() - 方法注释
- deleteUser() - 方法注释
- userId - 属性注释
🔄 In Progress: UserService
- 类注释
- findUserById() - 方法注释
- saveUser() - 方法注释
undefined✅ Completed: UserController
- 类注释
- createUser() - 方法注释
- updateUser() - 方法注释
- deleteUser() - 方法注释
- userId - 属性注释
🔄 In Progress: UserService
- 类注释
- findUserById() - 方法注释
- saveUser() - 方法注释
undefinedComment Quality Guidelines
注释质量指南
IMPORTANT: Comment Format Standards
This skill follows two standards:
- Standard JavaDoc (default): See javadoc-standards.md (within this skill)
- Java Coding Standards (strict): See java-coding-standards.md (within this skill)
The Java Coding Standards require:
- Description must be wrapped in tags:
<p><p>description</p> - Parameter types must be declared:
@param paramName paramType description - Return types must be declared:
@return returnType description - Exception types must be declared with full package name:
@exception java.lang.Exception description
Class Comments Should Include:
- Clear description of the class purpose (wrapped in tags if following Java Coding Standards)
<p> - Main responsibilities
- Usage examples (if complex)
- Related classes or components
- Author and version (if available)
Method Comments Should Include:
- Clear description of what the method does (wrapped in tags if following Java Coding Standards)
<p> - All parameters with descriptions and types
- Return value description with type
- Exceptions that may be thrown (with full package names)
- Usage examples (for complex methods)
- Side effects (if any)
Field Comments Should Include:
- Clear description of what the field represents (wrapped in tags if following Java Coding Standards)
<p> - Data type and constraints (if applicable)
- Default values (if applicable)
- Relationships to other fields (if applicable)
重要提示:注释格式标准
本技能遵循两种标准:
- 标准JavaDoc(默认):参见本技能内的javadoc-standards.md
- 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> - 数据类型和约束(如适用)
- 默认值(如适用)
- 与其他字段的关系(如适用)
Best Practices
最佳实践
- Be concise but complete: Comments should be clear and informative without being verbose
- Use JavaDoc format: Follow standard JavaDoc conventions
- Maintain consistency: Use consistent style across all comments
- Update todo list: Always update the todo list after completing each item
- One class at a time: Process one complete class before moving to the next
- Respect existing code: Don't modify code logic, only add comments
- Context-aware: Comments should reflect the actual code behavior and business context
- 简洁但完整:注释应清晰且信息丰富,避免冗长
- 使用JavaDoc格式:遵循标准JavaDoc约定
- 保持一致性:所有注释使用统一风格
- 更新待办列表:完成每项后务必更新待办列表
- 一次处理一个类:完成一个完整类后再处理下一个
- 尊重现有代码:不要修改代码逻辑,仅添加注释
- 结合上下文:注释应反映代码的实际行为和业务场景
Comment Templates
注释模板
For different component types, use appropriate templates from the directory:
templates/- - Controller class comments
templates/controller-comment-template.md - - Service interface comments
templates/service-comment-template.md - - Service implementation comments
templates/serviceimpl-comment-template.md - - Application Service comments (DDD)
templates/application-service-comment-template.md - - Domain Service comments (DDD)
templates/domain-service-comment-template.md - - Feign Service Interface comments
templates/feign-service-comment-template.md - - Mapper comments
templates/mapper-comment-template.md - - Entity class comments
templates/entity-comment-template.md - - DTO class comments
templates/dto-comment-template.md
针对不同组件类型,使用目录下的对应模板:
templates/- - Controller类注释模板
templates/controller-comment-template.md - - Service接口注释模板
templates/service-comment-template.md - - Service实现类注释模板
templates/serviceimpl-comment-template.md - - Application Service注释模板(DDD)
templates/application-service-comment-template.md - - Domain Service注释模板(DDD)
templates/domain-service-comment-template.md - - Feign Service Interface注释模板
templates/feign-service-comment-template.md - - Mapper注释模板
templates/mapper-comment-template.md - - Entity类注释模板
templates/entity-comment-template.md - - DTO类注释模板
templates/dto-comment-template.md
Comment Standards Reference
注释标准参考
Note: All reference documents are located within this skill's directory structure.
- Standard JavaDoc: See reference/javadoc-standards.md (local reference)
- Java Coding Standards (strict format): See reference/java-coding-standards.md (local reference)
When to use Java Coding Standards format:
- When the project explicitly follows 《JAVA 编程规范》
- When the project requires strict format with tags for descriptions
<p> - When parameter and return types must be explicitly declared in comments
注意:所有参考文档位于本技能的目录结构中。
- 标准JavaDoc:参见javadoc-standards.md(本地参考)
- Java编码规范(严格格式):参见java-coding-standards.md(本地参考)
何时使用Java编码规范格式:
- 当项目明确遵循《JAVA 编程规范》时
- 当项目要求严格格式,描述需用标签包裹时
<p> - 当注释中必须显式声明参数和返回类型时
Examples
示例
See the directory for complete examples:
examples/- - Controller commenting example
examples/controller-example.md - - Service commenting example
examples/service-example.md - - Entity commenting example
examples/entity-example.md - - Complete workflow example
examples/full-workflow-example.md
参见目录下的完整示例:
examples/- - Controller注释示例
examples/controller-example.md - - Service注释示例
examples/service-example.md - - Entity注释示例
examples/entity-example.md - - 完整工作流示例
examples/full-workflow-example.md
Keywords
关键词
English keywords:
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
Chinese keywords (中文关键词):
Java 代码注释, 添加注释, 生成注释, 代码注释, 文档注释, JavaDoc, 类注释, 方法注释, 属性注释, 字段注释, 给代码添加注释, 代码文档, Java 文档, 注释生成, 一句话添加注释, Controller 注释, Service 注释, Mapper 注释, Entity 注释, DTO 注释, 代码注解
英文关键词:
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 注释, 代码注解