代码注释规范Skill comment-guidelines

---

name: 代码注释规范 description: “代码注释规范。移除冗余注释，添加解释WHY而非WHAT的策略性注释。在修改代码时自动应用。” user-invocable: false

代码注释规范

本规范应在编写或修改代码时自动应用。

核心原则

1. 代码自文档化优先 - 使用清晰的命名和结构；注释是最后的手段
2. 解释WHY而非WHAT - 注释应解释意图和理由，而非具体机制
3. 减少认知负荷 - 让不明显的知识变得明确
4. 零冗余 - 绝不重复代码已表达的内容

何时添加注释

应添加注释的情况：

• 设计决策和权衡
• 不明显的行为或边界情况
• 接口约定（公共API、函数签名）
• 从代码中不明显的重要上下文
• 陷阱和微妙行为
• 跨模块依赖

不应添加注释的情况：

• 代码字面意思（不言自明的）
• 命名良好的变量/函数
• 标准模式和惯用法
• 代码中可见的实现细节

应用规则

修改代码时：

1. 移除 任何重复说明代码作用的注释
2. 保留 解释为何这样做的注释
3. 添加 仅针对不明显行为或设计决策的注释
4. 更新 现有注释，如果代码变更使其过时
5. 绝不 仅为填充空间或显得全面而添加注释

示例

// 差：重复说明显而易见的内容
// 将用户名设置为输入值
user.name = input.value;

// 好：解释不明显的行为
// 转换为小写，以便在搜索中进行不区分大小写的匹配
user.searchKey = user.name.toLowerCase();

// 差：记录不言自明的内容
// 循环遍历所有项目
for (const item of items) { ... }

// 好：解释为何采用此方法
// 反向处理，以便在迭代期间安全移除元素
for (let i = items.length - 1; i >= 0; i--) { ... }

自动应用

此技能无需显式调用。Claude应：

• 在编辑代码时始终应用这些原则
• 主动清理遇到的冗余注释
• 仅在能减少认知负荷的地方添加策略性注释