231 lines
4.5 KiB
Markdown
231 lines
4.5 KiB
Markdown
|
# 注释质量检查清单
|
|||
|
|
|
|||
|
|
本文档提供注释添加后的质量验证清单，用于确保注释符合规范要求。
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
|
|||
|
|
- [注释完整性检查](#注释完整性检查)
|
|||
|
|
- [注释内容检查](#注释内容检查)
|
|||
|
|
- [注释格式检查](#注释格式检查)
|
|||
|
|
- [代码完整性检查](#代码完整性检查)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 注释完整性检查
|
|||
|
|
|
|||
|
|
检查是否所有必需的代码元素都已添加注释：
|
|||
|
|
|
|||
|
|
### 函数/方法
|
|||
|
|
|
|||
|
|
- [ ] 所有公共函数都有多行注释
|
|||
|
|
- [ ] 所有私有函数都有注释（如果复杂）
|
|||
|
|
- [ ] 异步函数标记清晰
|
|||
|
|
|
|||
|
|
### 类/结构体
|
|||
|
|
|
|||
|
|
- [ ] 所有公共类都有多行注释
|
|||
|
|
- [ ] 抽象类标记清晰
|
|||
|
|
- [ ] 泛型类型参数有说明
|
|||
|
|
|
|||
|
|
### 属性/字段
|
|||
|
|
|
|||
|
|
- [ ] 所有公共属性都有注释
|
|||
|
|
- [ ] 静态属性有说明
|
|||
|
|
- [ ] 常量有用途说明
|
|||
|
|
|
|||
|
|
### 枚举
|
|||
|
|
|
|||
|
|
- [ ] 枚举本身有注释
|
|||
|
|
- [ ] 所有枚举成员都有注释
|
|||
|
|
- [ ] 每个成员的取值含义清晰
|
|||
|
|
|
|||
|
|
### 类型定义
|
|||
|
|
|
|||
|
|
- [ ] 接口/类型有注释
|
|||
|
|
- [ ] 所有属性有说明
|
|||
|
|
- [ ] 泛型参数有说明
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 注释内容检查
|
|||
|
|
|
|||
|
|
### 功能描述
|
|||
|
|
|
|||
|
|
- [ ] 功能描述清晰准确
|
|||
|
|
- [ ] 不重复代码已表达的信息
|
|||
|
|
- [ ] 描述了"做什么"而非"怎么做"
|
|||
|
|
|
|||
|
|
### 参数说明
|
|||
|
|
|
|||
|
|
- [ ] 每个参数都有说明
|
|||
|
|
- [ ] 参数类型标注正确
|
|||
|
|
- [ ] 联合类型参数有详细说明每个类型
|
|||
|
|
- [ ] 可选参数标注清晰
|
|||
|
|
- [ ] 参数的约束条件有说明
|
|||
|
|
|
|||
|
|
### 返回值说明
|
|||
|
|
|
|||
|
|
- [ ] 返回值类型正确
|
|||
|
|
- [ ] 返回值的含义清晰
|
|||
|
|
- [ ] 特殊情况（null、undefined）有说明
|
|||
|
|
|
|||
|
|
### 异常说明
|
|||
|
|
|
|||
|
|
- [ ] 所有可能抛出的异常都有说明
|
|||
|
|
- [ ] 异常发生条件清晰
|
|||
|
|
- [ ] 异常处理建议（如果有）
|
|||
|
|
|
|||
|
|
### 使用示例
|
|||
|
|
|
|||
|
|
- [ ] 至少包含一个基本使用示例
|
|||
|
|
- [ ] 示例代码可运行
|
|||
|
|
- [ ] 复杂函数有多个示例
|
|||
|
|
- [ ] 示例注释使用目标语言
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 注释格式检查
|
|||
|
|
|
|||
|
|
### 语言特定格式
|
|||
|
|
|
|||
|
|
- [ ] 符合语言特定的注释风格（JSDoc、Rustdoc 等）
|
|||
|
|
- [ ] 标签使用正确（@param、@returns 等）
|
|||
|
|
- [ ] 标签顺序合理
|
|||
|
|
|
|||
|
|
### 双语格式
|
|||
|
|
|
|||
|
|
- [ ] 所有注释都是中英双语
|
|||
|
|
- [ ] 英文描述在前，中文描述在后
|
|||
|
|
- [ ] 中英文之间有空行分隔
|
|||
|
|
- [ ] 参数描述使用斜杠分隔（`/`）
|
|||
|
|
|
|||
|
|
### 换行格式
|
|||
|
|
|
|||
|
|
- [ ] 注释文本在100字符左右换行
|
|||
|
|
- [ ] 列表项缩进一致
|
|||
|
|
- [ ] 代码块缩进正确
|
|||
|
|
|
|||
|
|
### 标点符号
|
|||
|
|
|
|||
|
|
- [ ] 中文内容使用中文标点
|
|||
|
|
- [ ] 英文内容使用英文标点
|
|||
|
|
- [ ] 引号使用正确
|
|||
|
|
- [ ] 无多余空格
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 代码完整性检查
|
|||
|
|
|
|||
|
|
**这是最关键的检查项**，确保注释添加过程中没有意外修改代码：
|
|||
|
|
|
|||
|
|
### 代码逻辑
|
|||
|
|
|
|||
|
|
- [ ] 未修改任何代码逻辑
|
|||
|
|
- [ ] 未添加新代码逻辑
|
|||
|
|
- [ ] 未删除代码逻辑
|
|||
|
|
|
|||
|
|
### 标识符
|
|||
|
|
|
|||
|
|
- [ ] 未修改任何变量名
|
|||
|
|
- [ ] 未修改任何函数名
|
|||
|
|
- [ ] 未修改任何类名
|
|||
|
|
- [ ] 未修改任何属性名
|
|||
|
|
|
|||
|
|
### 代码结构
|
|||
|
|
|
|||
|
|
- [ ] 未添加新代码行
|
|||
|
|
- [ ] 未删除代码行
|
|||
|
|
- [ ] 未重排代码行
|
|||
|
|
- [ ] 未修改代码顺序
|
|||
|
|
|
|||
|
|
### 代码格式
|
|||
|
|
|
|||
|
|
- [ ] 未修改缩进
|
|||
|
|
- [ ] 未修改换行
|
|||
|
|
- [ ] 未修改空格
|
|||
|
|
- [ ] 原有代码格式完全保留
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 特殊场景检查
|
|||
|
|
|
|||
|
|
### 复杂条件分支
|
|||
|
|
|
|||
|
|
如果为复杂条件添加了单行注释：
|
|||
|
|
|
|||
|
|
- [ ] 注释清晰解释条件逻辑
|
|||
|
|
- [ ] 注释说明为什么需要这个条件
|
|||
|
|
|
|||
|
|
### 复杂循环
|
|||
|
|
|
|||
|
|
如果为复杂循环添加了单行注释：
|
|||
|
|
|
|||
|
|
- [ ] 注释清晰解释循环目的
|
|||
|
|
- [ ] 注释说明边界条件
|
|||
|
|
|
|||
|
|
### 复杂表达式
|
|||
|
|
|
|||
|
|
如果为复杂表达式添加了单行注释：
|
|||
|
|
|
|||
|
|
- [ ] 注释清晰解释表达式含义
|
|||
|
|
- [ ] 注释说明计算逻辑
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 验证流程
|
|||
|
|
|
|||
|
|
### 1. 完整性验证
|
|||
|
|
|
|||
|
|
逐项检查上述完整性检查清单。
|
|||
|
|
|
|||
|
|
### 2. 内容审查
|
|||
|
|
|
|||
|
|
快速浏览注释内容，确保：
|
|||
|
|
|
|||
|
|
- 功能描述准确
|
|||
|
|
- 参数说明完整
|
|||
|
|
- 示例代码可运行
|
|||
|
|
|
|||
|
|
### 3. 格式验证
|
|||
|
|
|
|||
|
|
检查所有注释是否符合格式要求：
|
|||
|
|
|
|||
|
|
- 双语格式
|
|||
|
|
- 换行规则
|
|||
|
|
- 标点符号
|
|||
|
|
|
|||
|
|
### 4. 代码对比
|
|||
|
|
|
|||
|
|
将修改后的文件与原文件对比，确保：
|
|||
|
|
|
|||
|
|
- 只有注释被添加或修改
|
|||
|
|
- 所有代码逻辑完全一致
|
|||
|
|
|
|||
|
|
### 5. 测试验证（如可能）
|
|||
|
|
|
|||
|
|
如果项目有测试，运行测试确保代码功能未受影响。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 常见问题
|
|||
|
|
|
|||
|
|
### 问题：注释与代码不一致
|
|||
|
|
|
|||
|
|
**原因**：代码在添加注释后被修改
|
|||
|
|
**解决**：回退代码修改，只保留注释
|
|||
|
|
|
|||
|
|
### 问题：过多不必要的注释
|
|||
|
|
|
|||
|
|
**原因**：为简单代码添加了注释
|
|||
|
|
**解决**：删除明显多余的注释
|
|||
|
|
|
|||
|
|
### 问题：双语格式不统一
|
|||
|
|
|
|||
|
|
**原因**：部分注释遗漏中文或英文
|
|||
|
|
**解决**：补全所有双语注释
|
|||
|
|
|
|||
|
|
### 问题：示例代码无法运行
|
|||
|
|
|
|||
|
|
**原因**：示例与实际函数签名不符
|
|||
|
|
**解决**：修正示例代码或函数签名
|