2.0 KiB
2.0 KiB
name, description
| name | description |
|---|---|
| add-code-comments | 为用户指定的代码补充简洁、准确的变量和函数注释，并整理局部多余空行。适用于支持 // 注释的语言，仅在用户显式调用 $add-code-comments 时使用。 |
补充代码注释
为用户指定的函数、类、文件或目录补充有价值的代码注释，使代码更容易阅读。
只允许修改注释和空白格式，不得改变代码行为。
执行范围
- 读取当前目录适用的
AGENTS.md和项目规则。 - 只处理用户明确指定的文件、函数、类或目录。
- 如果用户没有指定处理范围，先询问，不要默认扫描整个项目。
- 处理目录或整个项目时，跳过：
- 第三方依赖；
- 自动生成文件；
- 编译产物；
- 缓存、日志和临时文件；
- 包含
auto-generated、generated code等标记的文件。
本 Skill 主要用于 C、C++、C#、Java、JavaScript、TypeScript 等支持 // 注释的语言。
如果目标语言不支持 // 注释，不得添加无效语法，应先向用户说明。
理解代码
添加注释前，先理解相关代码的真实作用。
必要时可以只读检查：
- 变量的赋值位置和使用位置；
- 函数的调用者；
- 参数的来源；
- 返回值的用途；
- 相关配置、接口和测试；
- 单位、坐标系、状态含义和边界条件。
无法从代码或现有资料确认的信息不要猜测，也不要为了增加注释数量而编造说明。
注释原则
注释应解释代码中不能直接看出的信息，例如：
- 变量的业务含义；
- 缩写的完整含义；
- 数值的单位；
- 坐标系和方向约定；
- 状态值或标志位的含义；
- 函数的主要目的；
- 不明显的输入输出约束；
- 算法采用这种写法的原因；
- 容易误用的边界条件；
- 重要副作用。
不要简单地把代码翻译成中文。
错误示例：
count++; // count 加一