---
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 加一
```