java-code-comments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When 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
```
.java
```
  files in the current directory and subdirectories
- Understand the project structure and architecture
- Identify relationships between classes (dependencies, inheritance, composition)
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
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

undefined

Todo List: Java Code Comments

Controller 层

Service 层

ServiceImpl 层

Mapper 层

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

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

undefined

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() - 方法注释

undefined

Comment 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:
```
description
```
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)
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)
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)
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编码规范要求：

描述必须用

标签包裹：
```
description
```
必须声明参数类型：
```
@param paramName paramType description
```
必须声明返回类型：
```
@return returnType description
```

异常类型必须声明完整包名：

@exception java.lang.Exception description

类注释应包含：

清晰的类用途描述（如果遵循Java编码规范，需用
```

```
标签包裹）
主要职责
使用示例（如果逻辑复杂）
相关类或组件
作者和版本信息（如有）

方法注释应包含：

清晰的方法功能描述（如果遵循Java编码规范，需用
```

```
标签包裹）
所有参数的描述和类型
返回值的描述和类型
可能抛出的异常（带完整包名）
使用示例（针对复杂方法）
副作用（如有）

字段注释应包含：

清晰的字段含义描述（如果遵循Java编码规范，需用
```

```
标签包裹）
数据类型和约束（如适用）
默认值（如适用）
与其他字段的关系（如适用）

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

templates/

directory:

templates/controller-comment-template.md

- Controller class comments

```
templates/service-comment-template.md
```
- Service interface comments

templates/serviceimpl-comment-template.md

- Service implementation comments

templates/application-service-comment-template.md

- Application Service comments (DDD)

templates/domain-service-comment-template.md

- Domain Service comments (DDD)

templates/feign-service-comment-template.md

- Feign Service Interface comments

```
templates/mapper-comment-template.md
```
- Mapper comments
```
templates/entity-comment-template.md
```
- Entity class comments
```
templates/dto-comment-template.md
```
- DTO class comments

针对不同组件类型，使用

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 Interface注释模板

```
templates/mapper-comment-template.md
```
- Mapper注释模板
```
templates/entity-comment-template.md
```
- Entity类注释模板
```
templates/dto-comment-template.md
```
- DTO类注释模板

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
When parameter and return types must be explicitly declared in comments

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

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

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

当项目明确遵循《JAVA 编程规范》时
当项目要求严格格式，描述需用
```

```
标签包裹时
当注释中必须显式声明参数和返回类型时

Examples

示例

See the

examples/

directory for complete examples:

```
examples/controller-example.md
```
- Controller commenting example
```
examples/service-example.md
```
- Service commenting example
```
examples/entity-example.md
```
- Entity commenting example
```
examples/full-workflow-example.md
```
- Complete workflow example

参见

examples/

目录下的完整示例：

```
examples/controller-example.md
```
- Controller注释示例
```
examples/service-example.md
```
- Service注释示例
```
examples/entity-example.md
```
- Entity注释示例
```
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 注释, 代码注解