注释过多

概述

注释过多是可舍弃类代码异味的一种，指代码中有过多解释性注释，尤其是解释代码"做了什么"而非"为什么"的注释，或者存在大量已注释掉的代码。

关键内容

1. 特征识别：
2. 注释在解释代码"做了什么"而不是"为什么"
3. 大段注释掉的代码
4. 长期存在的TODO/FIXME标记
5. 注释中带有道歉语气或解释复杂性的内容

6. 注释比代码本身还长

7. 负面影响：

8. 注释会过时且难以维护
9. 代码本身应该能够自解释
10. 死代码造成混淆和维护负担
11. 掩盖了代码设计的问题

12. 增加阅读和理解的复杂性

13. 好与坏的注释： ``` // BAD: 解释做了什么 // 遍历用户并检查是否活跃 for (const user of users) { if (user.status === 'active') { } }

// GOOD: 解释为什么 // 只保留活跃用户，未活跃用户由清理任务处理 const activeUsers = users.filter(u => u.isActive); ```

1. 重构策略：
2. Extract Method：通过方法名解释意图
3. Rename Method/Variable：通过良好命名提升清晰度
4. 删除注释掉的代码
5. Introduce Assertion：用断言代替解释性注释

来源

• Martin Fowler — 《重构：改善既有代码的设计》
• 代码异味 — 重构指导书

相关

• 代码异味 — 注释过多所属的异味类别
• 重构 — 解决方法
• 代码可读性 — 相关概念
• Clean Code — 相关理念
• Extract Method — 重构技巧