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