AI 写代码越多，注释越不能省——理由和你想的不一样

有了 AI 写代码你的注释反而更重要了最近跟几个开发者聊越来越多人开始不写注释。理由很充分AI 会自动生成文档还要什么注释、让 Cursor 帮我解释这段代码比注释清楚多了。、注释是给人读的现在 AI 能直接读懂代码逻辑。听起来都很合理。恰好全部反了。先看一组数据。GitClear 分析了 2020 到 2024 年间的 2.11 亿行代码变更结论让人不安重构相关的改动从 2021 年的 25% 跌到了 2024 年不足 10%而复制粘贴的代码比例从 8.3% 涨到了 12.3%。有史以来第一次开发者粘贴代码的频率超过了重构和复用代码的频率。GitClear 的创始人 Bill Harding 给这个现象起了个名字AI 诱发的技术债。仓促添加的代码对之后要维护它的团队来说是有毒的。这不是孤证。SonarSource 对 1149 名开发者的调查显示96% 的开发者不完全信任 AI 生成的代码在功能上是正确的。而 METR 的随机对照实验发现有经验的开发者主观感觉 AI 让他们快了 20%——客观测试显示他们实际上慢了 19%。速度是幻觉。可维护性的下滑是真实的。那这跟注释有什么关系有一件事很少有人说清楚AI 写代码时最需要的不是代码本身而是意图。Google Chrome 工程师 Addy Osmani 在 2025 年底写了一篇广泛被引用的工作流文章里面有一句话点醒了我LLM 是字面派——它们会按照指令来。用注释和规则来引导 AI给它详细的、有背景的指令。他举了个例子在把代码片段发给 AI 之前先加一行注释——这是 X 的当前实现。我们要扩展它来完成 Y但要小心不要破坏 Z。注意这不是解释代码在做什么的注释。这是解释为什么要这样做以及不能破坏什么的注释。这正是 AI 最缺的那种信息。AI 能通过代码推断出for循环在遍历什么。但它推断不出这里用 O(n²) 而不是 O(n log n) 的原因是数据集永远不会超过 100 条而且调用方依赖了稳定的顺序。那行写着// maintain insertion order, dataset always small的注释是让 AI 别在优化里给你挖坑的唯一防线。代码说明的是what。注释承载的是why。AI 会写 what从来不知道 why。这里有一个反直觉的地方值得停下来想一想。很多人放弃写注释是因为AI 能自动生成文档。这是真的。把一段函数扔给 Claude它能写出相当不错的 JSDoc解释参数、返回值、函数用途。但那是代码写完之后补的文档是对 what 的描述。真正有价值的注释是在写代码之前或之中留下的是对 why 的记录。两件事差了一个维度。一个是翻译。一个是记忆。AI 能做翻译。但它永远无法替你记住三个月前那个架构决策背后的权衡无法记住那个 bug 是怎么出现又怎么绕过去的无法记住那段看起来很蠢的写法是因为某个第三方库的历史遗留问题。那些不写注释的人正在把这些知识带走——带进自己的脑子里随着记忆衰退一起消失。现在再往前想一步。AI coding 工具正在让每个人写越来越多的代码代码库以前所未有的速度膨胀。膨胀的代码库加上越来越稀疏的注释结果是你的 AI 也读不懂它了。这不是比喻。AI coding 工具的核心工作原理是把你的代码库当作上下文喂给模型。代码越多上下文越大模型越难找到最相关的部分。这也是为什么有整个行业在做repo map、代码索引、上下文压缩——本质上是在为 AI 生成一张代码地图包含文件名、函数签名、类定义让 AI 能鸟瞰整个项目而不把整个 context budget 都烧完。在这样的工具里注释的作用从辅助说明变成了信号密度。一段有清晰注释的函数AI 能在几百个 token 里读懂它的完整语义。一段没注释的函数AI 要么猜要么花大量 token 去追踪调用链。不写注释不只是在为难同事。是在为难你自己的 AI 工具。Stack Overflow 2025 调查发现开发者在遇到问题时最常做的事是阅读注释——对人类传递上下文的需求从未消失。这个需求在 AI 时代只是多了一个接收对象你的 AI 协作者。注释不是过时的仪式。它是在一个日益依赖 AI 的开发流程里将意图注入代码库的唯一可靠方式。AI 能帮你写代码。但没有人能帮你写清楚你为什么要这样做。那是你的工作。现在比以前更重要了。转发给最近开始不写注释的同事——他可能需要看一看。