# 注释质量检查清单

本文档提供注释添加后的质量验证清单，用于确保注释符合规范要求。

## 目录

- [注释完整性检查](#注释完整性检查)
- [注释内容检查](#注释内容检查)
- [注释格式检查](#注释格式检查)
- [代码完整性检查](#代码完整性检查)

---

## 注释完整性检查

检查是否所有必需的代码元素都已添加注释：

### 函数/方法

- [ ] 所有公共函数都有多行注释
- [ ] 所有私有函数都有注释（如果复杂）
- [ ] 异步函数标记清晰

### 类/结构体

- [ ] 所有公共类都有多行注释
- [ ] 抽象类标记清晰
- [ ] 泛型类型参数有说明

### 属性/字段

- [ ] 所有公共属性都有注释
- [ ] 静态属性有说明
- [ ] 常量有用途说明

### 枚举

- [ ] 枚举本身有注释
- [ ] 所有枚举成员都有注释
- [ ] 每个成员的取值含义清晰

### 类型定义

- [ ] 接口/类型有注释
- [ ] 所有属性有说明
- [ ] 泛型参数有说明

---

## 注释内容检查

### 功能描述

- [ ] 功能描述清晰准确
- [ ] 不重复代码已表达的信息
- [ ] 描述了"做什么"而非"怎么做"

### 参数说明

- [ ] 每个参数都有说明
- [ ] 参数类型标注正确
- [ ] 联合类型参数有详细说明每个类型
- [ ] 可选参数标注清晰
- [ ] 参数的约束条件有说明

### 返回值说明

- [ ] 返回值类型正确
- [ ] 返回值的含义清晰
- [ ] 特殊情况（null、undefined）有说明

### 异常说明

- [ ] 所有可能抛出的异常都有说明
- [ ] 异常发生条件清晰
- [ ] 异常处理建议（如果有）

### 使用示例

- [ ] 至少包含一个基本使用示例
- [ ] 示例代码可运行
- [ ] 复杂函数有多个示例
- [ ] 示例注释使用目标语言

---

## 注释格式检查

### 语言特定格式

- [ ] 符合语言特定的注释风格（JSDoc、Rustdoc 等）
- [ ] 标签使用正确（@param、@returns 等）
- [ ] 标签顺序合理

### 双语格式

- [ ] 所有注释都是中英双语
- [ ] 英文描述在前，中文描述在后
- [ ] 中英文之间有空行分隔
- [ ] 参数描述使用斜杠分隔（`/`）

### 换行格式

- [ ] 注释文本在100字符左右换行
- [ ] 列表项缩进一致
- [ ] 代码块缩进正确

### 标点符号

- [ ] 中文内容使用中文标点
- [ ] 英文内容使用英文标点
- [ ] 引号使用正确
- [ ] 无多余空格

---

## 代码完整性检查

**这是最关键的检查项**，确保注释添加过程中没有意外修改代码：

### 代码逻辑

- [ ] 未修改任何代码逻辑
- [ ] 未添加新代码逻辑
- [ ] 未删除代码逻辑

### 标识符

- [ ] 未修改任何变量名
- [ ] 未修改任何函数名
- [ ] 未修改任何类名
- [ ] 未修改任何属性名

### 代码结构

- [ ] 未添加新代码行
- [ ] 未删除代码行
- [ ] 未重排代码行
- [ ] 未修改代码顺序

### 代码格式

- [ ] 未修改缩进
- [ ] 未修改换行
- [ ] 未修改空格
- [ ] 原有代码格式完全保留

---

## 特殊场景检查

### 复杂条件分支

如果为复杂条件添加了单行注释：

- [ ] 注释清晰解释条件逻辑
- [ ] 注释说明为什么需要这个条件

### 复杂循环

如果为复杂循环添加了单行注释：

- [ ] 注释清晰解释循环目的
- [ ] 注释说明边界条件

### 复杂表达式

如果为复杂表达式添加了单行注释：

- [ ] 注释清晰解释表达式含义
- [ ] 注释说明计算逻辑

---

## 验证流程

### 1. 完整性验证

逐项检查上述完整性检查清单。

### 2. 内容审查

快速浏览注释内容，确保：

- 功能描述准确
- 参数说明完整
- 示例代码可运行

### 3. 格式验证

检查所有注释是否符合格式要求：

- 双语格式
- 换行规则
- 标点符号

### 4. 代码对比

将修改后的文件与原文件对比，确保：

- 只有注释被添加或修改
- 所有代码逻辑完全一致

### 5. 测试验证（如可能）

如果项目有测试，运行测试确保代码功能未受影响。

---

## 常见问题

### 问题：注释与代码不一致

**原因**：代码在添加注释后被修改
**解决**：回退代码修改，只保留注释

### 问题：过多不必要的注释

**原因**：为简单代码添加了注释
**解决**：删除明显多余的注释

### 问题：双语格式不统一

**原因**：部分注释遗漏中文或英文
**解决**：补全所有双语注释

### 问题：示例代码无法运行

**原因**：示例与实际函数签名不符
**解决**：修正示例代码或函数签名