---

name: 文档化代码注释 description: 自文档化代码和最小注释的标准。用于审计内联文档或决定何时注释增加价值而非混乱。

代码注释

核心原则： 最好的注释是你不需要写的注释。

层次结构

1. 使代码自文档化（命名、结构）
2. 使用类型系统来定义契约
3. 只添加解释原因的注释，而不是描述做什么

何时不注释

避免	原因
// 获取用户名	重复代码
@param {string} email	类型已经文档化
过时的注释	误导性 > 缺失

何时注释

解释原因，而不是做什么

// 使用指数退避 - 服务在3次快速失败后限速
const backoffMs = Math.pow(2, attempts) * 1000;

陷阱和边缘情况

// 重要：假设UTC - 本地时区导致日期漂移
const dayStart = new Date(date.setHours(0, 0, 0, 0));

外部上下文

// Safari flexbox bug的变通方案 (JIRA-1234)
// 根据RFC 7231 §6.5.4，为缺失资源返回404

性能决策

// 使用Map进行O(1)查找 - 在n>100时比array.find()快3倍
const userMap = new Map(users.map(u => [u.id, u]));

在注释前重构

替代注释	重构为
// 获取活跃用户	const activeUsers = users.filter(u => u.isActive)
// 86400000毫秒 = 1天	const ONE_DAY_MS = 24 * 60 * 60 * 1000
// 处理错误情况	提取到 handleAuthError(err)

TODO格式

// ✅ TODO(JIRA-567): 当Q1 2025可用时替换为批量API
// ❌ TODO: 稍后修复

审计清单

1. 必要性 - 代码是否可以重构以消除注释？
2. 准确性 - 注释是否匹配当前行为？
3. 价值 - 它解释原因了吗，而不是做什么？
4. 可操作性 - TODO是否有工单引用？