清晰代码不等于干净代码：注释从来不是问题
来源：dev.to — 2026-09-21
📋 概述
作者正面反驳「好代码不需要注释」这条被行业当成信条的说法。他承认自己也想拥有打开文件一眼就懂的代码库，但现实中总有三类代码无法自我解释：从未以结构为目标写出来的代码、写得漂亮却解决着需要盯着看五小时的复杂问题的代码、以及干净可读却出于某种代码里看不见的理由而存在的代码。他用正则表达式和「为什么是 47」两个例子说明：代码记录的是决策，注释记录的是推理，丢掉推理，决策看起来就像个 bug。至于「把理由写进提交信息」，他反驳得更狠——没人会去 git blame 一段看起来正常的代码，blame 还会在格式化、改名、拆分和 squash merge 中衰减，最终理由只留在写它的人脑子里。
🔑 核心要点
- 好注释只做四件事：翻译（正则、位运算、数学公式）、解释看起来错误或随意的选择、警告改动会破坏什么、记录带保质期的决策。
- 「代码已经够清楚」的反例：命名规范的常量 MaxConcurrentRequests = 47，文档说上限是 50，于是有人改成 50，几周后真实流量下开始随机被拒。
- git 历史最致命的缺陷是：没人会对看起来正常的代码跑 git blame，而注释能在你犯错之前拦住你。
- blame 会衰减：一次格式化、一次改名、一次 squash merge，责任行就指向「apply editorconfig」这样的提交，查证从检索变成了考古。
- 最坏情况不过是「改代码要顺手改注释」，而注释就在你正在编辑的那一行上面，这不是额外开销，这是工作本身。
💡 金句
代码记录的是决策，注释记录的是推理；丢掉推理，决策看起来就像个 bug。
👍 0
👎 0
← 返回 dev.to 首页