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