yy-comment
描述
为代码添加注释的通用技能,支持多种编程语言和标记语言。遵循跨语言通用规则,并按语言加载特定注释规范;语言特定规则与通用规则冲突时,以语言特定规则优先。
使用场景
当用户表达以下意图时触发:
- 为代码文件或指定函数/类/方法添加注释
- 补充文档注释(docstring、Javadoc、KDoc、PHPDoc 等)
- 为代码逻辑添加解释性注释
- 为 HTML/Vue 模板添加结构注释
- 为 CSS/SCSS/LESS 添加样式注释
不应触发:
- 用户要求实现新功能、修改代码逻辑或删除代码
- 文件已有完整注释且用户未明确要求补充
- 用户要求为每行代码都加注释(过度注释)
规则层级
通用规则定义在 resources/common.md,语言特定规则定义在 resources/{语言}.md。
当特定语言的规则与通用规则冲突时,以特定语言的规则优先。
支持的语言
- Python →
resources/python.md - Java →
resources/java.md - C/C++ →
resources/c-cpp.md - C# →
resources/csharp.md - Go →
resources/go.md - Rust →
resources/rust.md - Swift →
resources/swift.md - Kotlin →
resources/kotlin.md - Ruby →
resources/ruby.md - PHP →
resources/php.md - Shell/Bash →
resources/shell.md - SQL →
resources/sql.md - JavaScript/TypeScript →
resources/js-ts.md - HTML/CSS →
resources/html-css.md
遇到未列出语言的文件时,使用通用规则和该语言的注释语法常识处理。
指令
步骤 1. 确定范围
决策分支:
- 用户指定文件:读取目标文件
- 用户指定函数/类/方法:定位目标
- 用户未指定:通过
git diff查找变更文件,过滤为支持类型的文件
对于超过 500 行的文件,先告知用户文件规模,确认后再执行。
步骤 2. 识别语言并加载规则
- 根据文件扩展名识别语言
- 加载
resources/common.md中的通用规则 - 加载
resources/{语言}.md中的语言特定规则(如存在) - 当特定语言的规则与通用规则冲突时,以语言特定规则优先
步骤 3. 添加注释
按通用规则和语言特定规则执行:
- 为函数/类/方法/接口添加文档注释
- 为重要模块级常量和类型定义添加注释
- 在关键逻辑步骤前添加内部注释(解释"为什么")
- 跳过自解释代码和显而易见的逻辑
- 已有注释内容正确则保留,仅在缺失处补充;内容过时则修正
步骤 4. 输出结果
修改目标文件后,报告:
- 添加了注释的函数/类/接口/模块列表
- 各类注释数量:文档注释 N 处、内部逻辑注释 N 处
安全边界
- 不修改代码逻辑、不删除已有代码
- 不删除已有的正确注释
- 不为自解释代码强制添加注释
- 不修改自动生成的代码文件(如构建产物、编译输出)
相关资源
resources/common.md- 跨语言通用注释规则(判断标准、避免模式、标注约定)resources/{语言}.md- 各语言特有的注释语法和规范