code-commentator

name code-commentator description 代码注释补充与规范化专家，自动识别代码文件类型，为函数、类、方法、属性等代码元素添加专业双语注释。当用户提及"添加注释"、"补充注释"、"规范化注释"、"代码注释"、"annotate code"、"add comments"或需要为代码添加文档注释时使用本技能。本技能也可被其他技能（如 executing-plans）在代码完成后自动调用。 license MIT metadata {"version":"1.2.0"} 代码注释补充与规范化技能 本技能提供代码注释的系统性补充与规范化处理能力，自动识别代码文件类型，应用相应的注释规范，确保生成的注释准确、完整且符合双语要求。 触发条件 当检测到以下情况时，主动激活此技能： 用户直接调用 ： 用户提及添加或补充注释："添加注释"、"补充注释"、"增加注释" 用户提及规范化注释："规范化注释"、"统一注释风格"、"注释规范" 用户提及代码注释需求："给代码加注释"、"代码缺少注释"、"注释不完整" 用户提及特定注释类型："函数注释"、"类注释"、"JSDoc"、"docstring" 英文触发词："add comments"、"annotate code"、"code documentation"、"JSDoc" 其他技能自动调用 ： executing-plans 技能在任务完成后自动调用（如果代码需要注释） 在测试通过后、代码提交前的自动化流程中 被其他技能调用 当被 executing-plans 或其他技能调用时： 接收参数 ： target_files ：需要添加注释的文件路径列表（必需） comment_priority ：注释优先级（可选：high/medium/low） focus_areas ：重点注释区域（可选：如"公共API"、"核心逻辑"） 执行模式 ： 跳过用户确认，直接执行 使用默认的双语注释格式 自动识别代码复杂度，智能添加注释 完成后返回处理结果摘要 绝对禁止事项 ⚠️ 严禁修改任何代码内容 。本技能只能添加或修改注释，不得： ❌ 修改代码逻辑 ❌ 修改变量名、函数名、类名等标识符 ❌ 修改代码结构（如添加、删除、重排代码行） ❌ 修改代码格式（如缩进、换行、空格） 唯一允许的操作 ：为代码添加注释或修改现有注释。 双语注释要求 所有注释必须同时包含 中英文双语说明 ，格式为： 英文描述在前 空行分隔 中文描述在后 注释格式参考 详细的多语言注释格式示例已迁移到 references 目录： 参考文件 内容 comment-formats.md 各种编程语言的注释格式代码示例 writing-style.md 语气与口吻规范、语言语法要求 quality-checklist.md 注释质量验证清单 重要 ：添加注释前，先阅读 comment-formats.md 确保使用正确的语言格式。 核心注释原则 必须添加多行注释的元素 以下代码元素 必须 添加多行文档注释： ✅ 函数/方法 ✅ 类/结构体/接口 ✅ 公共属性/字段 ✅ 枚举及其成员 ✅ 类型定义 ✅ 模块/命名空间 需要评估是否添加注释 仅在代码逻辑不够直观时才添加单行注释： ⚠️ 复杂的条件分支逻辑 ⚠️ 复杂的循环结构 ⚠️ 复杂的表达式 ⚠️ 重要的变量声明（用途不明显时） 不需要添加注释的情况 代码本身已足够清晰，无需添加注释： ❌ 简单的条件判断（如 if (isValid) ） ❌ 简单的循环（如 for (const item of items) ） ❌ 变量名已清晰表达用途的声明（如 const userName = user.name ） ❌ 标准的 getter/setter 方法 ❌ 一目了然的赋值语句 判断标准 添加注释前，先问自己 ： 不看注释，能否快速理解这段代码的意图？ 代码命名是否足够清晰？ 注释是否提供了代码本身无法表达的信息？ 如果以上问题的答案表明代码已足够清晰，则不需要添加注释。 注释插入规则 元素类型 插入位置 要求 函数/方法注释 紧贴在函数声明上方 不留空行 类注释 紧贴在类声明上方 不留空行 属性注释 紧贴在属性声明上方 不留空行 单行注释 放在代码行上方 与代码保持相同缩进 函数/方法注释要点 函数/方法注释必须包含： 功能描述 ：清晰描述函数的功能和用途 入参说明 ：每个参数的类型和用途 出参说明 ：返回值的类型和含义 异常说明 ：可能抛出的异常及其条件（如有） 使用示例 ：至少一个基本使用示例 联合类型参数 当参数为联合类型时， 必须 详细说明每个类型： @param input - The input data to process. Can be : - `string` : A string value to parse / 要解析的字符串值 - `Buffer` : A buffer containing raw data / 包含原始数据的缓冲区 - `ReadableStream` : A stream to read data from / 要读取数据的流 多种传参方式 支持多种传参方式时，提供 不同场景的使用示例 ： @example // Create user with name only const user = createUser ( 'John' ); // Create user with options object const user = createUser ({ name : 'John' , age : 25 , email : 'john@example.com' }); 执行流程 文件扫描流程 接收用户指定的文件或目录 递归扫描所有代码文件 按语言类型分组处理 生成处理计划 单文件处理流程 读取文件内容 解析代码结构（AST 或正则匹配） 识别需要注释的代码元素 检查现有注释的完整性 生成符合规范的注释 将注释插入到正确位置 写入更新后的文件 进度报告格式 处理过程中实时报告进度： ## 注释处理进度 ### 已完成 (3/10) - ✅ src/utils/helper.ts (添加了 5 个函数注释) - ✅ src/models/user.ts (添加了 2 个类注释, 8 个属性注释) - ✅ src/api/client.ts (添加了 3 个函数注释) ### 处理中 - 🔄 src/services/auth.ts ### 待处理 (6/10) - ⏳ src/config/index.ts - ... 快速参考 注释格式速查 /** * English description of the function. * * 中文描述函数的功能。 * * @param paramName - English description / 中文描述 * @returns English description / 中文描述 * @throws { ErrorType } English description / 中文描述 * @example * const result = functionName('value'); */ function functionName ( paramName : string ): Result {} 注意事项速记 只添加注释 ：严禁修改任何代码内容 保持一致性 ：同一文件内注释风格必须一致 准确性优先 ：注释内容必须准确反映代码功能 避免过度注释 ：如果代码本身足够清晰，则不需要添加注释 简洁明了 ：注释应有实际价值 示例可运行 ：所有使用示例必须是可运行的代码 参考文档 📄 comment-formats.md - 详细格式示例 📄 writing-style.md - 写作风格指南 📄 quality-checklist.md - 质量验证清单