文章认为，代码注释不仅应解释"为什么"，也应说明"在做什么"。作者指出，虽然变量命名应清晰自明，但注释补充说明仍有助于避免理解偏差。同时，保留代码背后的原因（如修复特定bug）在注释中也很重要，因为仅依赖提交记录或测试可能不够可靠。

标题：或许注释应该解释"是什么"

来源链接：https://www.hillelwayne.com/post/what-comments/

发布时间：2017年12月5日

文章核心观点： 1. 传统观点认为注释只需解释"为什么"（代码意图），而非"是什么"（代码功能），但作者提出不同见解 2. 反对用注释替代清晰代码的案例： - 使用单字母变量名（如w=10）需要注释说明，不如直接使用描述性变量名（weight=10） - 代码自解释性不足时，阅读者需要频繁回溯上下文，容易产生误解

3. 支持注释解释"为什么"的论据：

   • 将代码意图放在提交信息或测试中会导致追溯困难
   • 示例：重复调用XYZ.clear()的注释能直接说明解决特定bug的需求

4. 代码重构的潜在问题：

   • 通过提取方法重构代码（如将10行代码拆分为6个方法）可能导致需要频繁跳转阅读
   • 作者认为适当添加"是什么"注释（如解释正则表达式匹配模式）有时比过度拆分更高效

5. 核心结论：

   • 信息获取成本是关键考量
   • 既反对用注释弥补糟糕代码，也反对教条式拒绝"是什么"注释
   • 理想做法是根据具体场景，选择最减少认知负荷的方式（清晰的代码或恰当的注释）

注：删除了关于编程语言学习的脚注内容，因其与注释主题关联性较弱。保留了重构代码的具体示例以说明观点，但简化了部分实现细节。

评论内容总结

1. 对"Uncle Bob"编程风格的批评

• 主要观点：过度拆分方法（每行代码一个方法）会降低代码可读性和调试效率
• 关键引用：
  • "It's a constant frustration of pressing the 'go to definition' key over and over" (awesan)
  • "jumping through 6 methods instead of one decreases readability quite a bit" (rokkamokka)

2. 注释的必要性与类型

• 主要观点：注释应解释代码意图，特别是领域知识和复杂逻辑
• 关键引用：
  • "Bank transfers appear as two transactions...We match them by looking for equal-opposite amounts within a 3-day window" (jackfranklyn)
  • "Comments should explain everything, but via links" (CuriouslyC)

3. 命名与代码结构的重要性

• 主要观点：好的命名可以减少对注释的依赖，但需要平衡简洁性和明确性
• 关键引用：
  • "Names capture ideas...The more clear and descriptive a name...the less cognitive load" (frumiousirc)
  • "Replace all symbols...better conveyed by improving the function name" (StellarScience)

4. 注释实践建议

• 主要观点：应根据具体情况灵活使用注释，避免教条主义
• 关键引用：
  • "commenting should add relevant information that is missing" (panstromek)
  • "when in doubt, write a comment...in your own words" (mattacular)

5. 不同编程场景的需求

• 主要观点：不同领域（如数据科学、会计软件）对注释有不同需求
• 关键引用：
  • "a lot of my R code are dplyr-chains...saves time to comment" (aquafox)
  • "half my 'what' comments are actually explaining business rules" (jackfranklyn)

6. 对极端观点的反对

• 主要观点：既反对完全不用注释，也反对过度注释
• 关键引用：
  • "I rarely saw teams which over-document, under-documenting is usually the case" (xlii)
  • "overexplaining is only bad when it's your wife or girlfriend" (drivingmenuts)

总结：评论普遍认为代码可读性是核心目标，注释和代码结构都应服务于此。多数人反对教条的"Uncle Bob"风格，主张根据实际需求灵活使用注释，特别是在解释领域知识和复杂逻辑时。好的命名可以部分替代注释，但不能完全取代。不同编程场景需要不同的注释策略。