⚡

代码注释完善Skill improve-comments

该技能用于完善、补充或重构代码注释，依据代码逻辑与语言规范生成高信息密度注释，强调解释“为什么”和约束，覆盖 Java Javadoc、Python、JavaScript/TypeScript、Go，并执行注释净化与术语统一。关键词：代码注释完善、Javadoc、API文档、代码审查、注释重构、Java、Python、TypeScript、Go、文档生成、代码可维护性、SEO。

后端开发 0 次安装 0 次浏览 更新于 11/11/2026
名称 improve-comments
描述 用于完善、补充或重构代码注释。当用户要求“完善注释”、“添加文档”、“写注释”或“review 注释”时，应使用此技能。它会根据代码逻辑自动生成符合语言规范（特别擅长 Java Javadoc，同时也支持 Python、JS/TS、Go 等）的详细注释。

代码注释完善技能

目标

分析给定的代码块或文件，生成清晰、准确、且具有高信息密度的注释。核心准则是：解释“为什么（Why）”这么做，以及“有什么约束（Constraints）”，而不仅仅是复述“是什么（What）”。

全局原则

  • 自解释代码优先：如果代码本身命名清晰（如 isValidEmail），注释应补充校验的具体规则（如“仅允许 ASCII 字符且域名必须包含点号”），而非重复方法名。
  • 警示性注释：若涉及并发锁、性能瓶颈（O(n^2)）、副作用（如修改全局状态）或历史遗留 Bug（@Deprecated），务必添加显式说明。
  • Nullability 显式标记：在 Java 中，注释应明确指出参数和返回值是否可为 null。

语法规范（分语言详解）

1. Java（Javadoc 标准）—— 重点详细规范

Java 注释必须严格遵循 Javadoc 语法（/** ... */），用于生成 API 文档。

A. 类 / 接口（Class / Interface）级别

每个公开的类或接口都必须包含 Javadoc，说明其职责、设计意图和线程安全性。

模板结构：

/**
 * 类的简短描述（通常为一句，以句号结尾）。
 * <p>
 * 详细描述：说明类的核心功能、在系统中所处的位置，以及主要的使用场景。
 * 如果类实现了某个设计模式，请在此注明（如：此实现采用单例模式 / 策略模式）。
 * </p>
 * <p>
 * <b>线程安全说明：</b> 指明该类是否线程安全。若非线程安全，说明外部同步机制。
 * </p>
 *
 * @author 作者名（我定义为guocq）
 * @since 引入该类的 JDK 或项目版本号
 * @see 相关类（如跳转到父类或策略接口）
 */
public class UserService { ... }

示例：

/**
 * 用户身份认证服务，负责登录、登出和 Token 刷新。
 * <p>
 * 该服务集成了 Spring Security，并缓存了用户的权限信息。
 * <b>线程安全说明：</b> 该类的所有公共方法均为无状态操作，是线程安全的。
 * </p>
 *
 * @since 2.0
 * @see com.example.security.TokenProvider
 */
@Service
public class AuthService { ... }

B. 方法（Method）级别

方法注释必须包含功能描述，并使用标准标签说明参数、返回值和异常。

标签顺序强制规范：@param → @return → @throws → @since（可选）。

模板结构：

/**
 * 描述该方法的核心职责（使用第三人称单数，如“获取用户信息”）。
 * <p>
 * 详细描述（可选）：补充业务逻辑的特殊性，例如“如果缓存中存在则直接返回，否则查询数据库”。
 * 若该方法有副作用（如修改传入对象状态），必须在此说明。
 * </p>
 *
 * @param paramName 参数描述（必须包含业务含义，如果禁止传 null，显式标注：must not be null）
 * @param otherParam 其他参数描述（约束条件如“长度必须介于 1 到 20 之间”）
 * @return 返回值描述（说明什么情况下返回什么值，若可能返回 null 需特别说明）
 * @throws IllegalArgumentException 如果传入参数不符合约束条件
 * @throws IllegalStateException 如果当前服务状态不满足调用条件（如未初始化）
 * @since 版本号（若该方法为新加）
 */
public ReturnType methodName(ParamType paramName, ...) { ... }

实际 Java 示例：

/**
 * 根据用户 ID 查询用户详细信息。
 * <p>
 * 内部优先从本地缓存（Caffeine）获取，缓存未命中时再访问数据库。
 * 此操作不修改任何持久化数据。
 * </p>
 *
 * @param userId 用户唯一标识，必须不为 null 且大于 0
 * @return 用户详情对象，若数据库中不存在该 ID 则返回 null（不会抛出异常）
 * @throws IllegalArgumentException 如果 userId 为 null 或小于等于 0
 */
@Nullable
public UserDetail getUserById(@NonNull Long userId) {
    // ...
}

C. 字段（Field）级别

公共常量（public static final）和带有复杂配置含义的成员变量必须加注释。

规范：

  • 常量：说明其配置用途和默认值来源。
  • 成员变量：若涉及并发可见性（如 volatile），说明其状态转换规则。

示例：

/**
 * 连接超时时间（毫秒）。
 * 默认值 3000ms，可通过系统属性 "app.connect.timeout" 覆盖。
 */
public static final int CONNECT_TIMEOUT = 3000;

/**
 * 当前活跃的 WebSocket 会话计数器。
 * 由 {@code synchronized} 块保护，修改时需获取类锁。
 */
private volatile int activeSessionCount;

D. 包级别（Package）注释

如果需要，在 package-info.java 文件中为整个包添加注释，说明该包的核心职责和主要模块划分。

示例（package-info.java）：

/**
 * 提供数据访问对象（DAO）和数据库映射。
 * <p>
 * 本包采用 Spring Data JPA 实现，所有 Repository 接口均继承自 JpaRepository。
 * </p>
 */
package com.example.repository;

2. Python（Google Style / NumPy Style）

  • 函数：使用三重双引号 """。
  • 必须包含：功能描述、Args（参数类型及含义）、Returns、Raises。
  • 类型提示：优先使用内置类型注解（def foo(x: int) -> str:），注释中可省略类型，专注于含义。
def fetch_data(url: str, timeout: int = 30) -> dict:
    """
    从指定 URL 获取 JSON 数据。

    Args:
        url: 目标 API 地址，必须包含协议头（http/https）。
        timeout: 请求超时时间（秒），默认为 30。

    Returns:
        解析后的 JSON 字典。若服务器返回 404，则返回空字典。

    Raises:
        ConnectionError: 当网络不可达时抛出。
    """
    pass

3. JavaScript / TypeScript（JSDoc）

  • 必须使用 /** ... */。

  • 标签：@param（包含类型和描述）、@returns、@throws、@typedef。

  • 类型：充分利用 TypeScript 类型系统，注释中可简化类型标注，重点描述业务逻辑。

    /**
 * 格式化日期为本地化字符串。
 *
 * @param date - 待格式化的日期对象，不允许为 null。
 * @param locale - 语言区域标识，如 'zh-CN'，默认为 'en-US'。
 * @returns 格式化后的日期字符串，格式为 'yyyy/MM/dd'。
 * @throws {TypeError} 如果 date 参数不是有效的 Date 对象。
 */
function formatLocalDate(date: Date, locale: string = 'en-US'): string {
    // ...
}

4. Go（标准 Doc 注释）

  • 紧贴函数声明，使用 //。
  • 函数注释：以函数名开头（如 // ParseConfig 解析...），描述参数、返回值和副作用。
  • 包注释：在 doc.go 或主文件顶部用 /* ... */ 编写。
// ParseConfig 从指定路径读取 YAML 配置文件并反序列化为 Config 结构体。
// 如果文件不存在，返回一个包含默认配置的 Config 对象。
// 参数 path: 配置文件的绝对路径。
// 返回: (*Config, error) 当文件格式错误时，error 非空。
func ParseConfig(path string) (*Config, error) {
    // ...
}

注释内容净化规则

在执行注释完善时，必须主动执行以下“净化”操作：

  1. 删除无意义废话：如 // 设置名字 紧跟在 setName() 前面，直接删除。
  2. 修复错别字和语法错误。
  3. 更新过期注释：如果代码逻辑已变但注释未更新（常见于 Bug 修复），必须重写注释以匹配当前逻辑。
  4. 统一团队术语：例如，若团队统一称 “客户” 而非 “用户”，需统一替换。

输出格式

完成注释添加后，请按以下格式回复：

  1. 变更摘要：用列表简要列出为哪些类/方法添加或修改了注释（例如：“已为 UserService 类添加线程安全说明；已为 getUserById 方法补充了 @throws 标签”）。
  2. 完整代码：直接输出添加注释后的完整文件内容（若代码量较大，可仅输出修改部分，但推荐输出完整文件以便复制）。