摘要：前几天刷到个帖子，十年码龄的技术负责人用AI两周生成1.2万行代码，最后却只能推倒重来。

前几天刷到个帖子，十年码龄的技术负责人用AI两周生成1.2万行代码，最后却只能推倒重来。

他说AI写的代码看着干净能用，后续维护时却像拆盲盒，没一句注释，自己都忘了逻辑在哪，这场景我太熟悉了。

作为写代码快十年的老鸟，我见过太多同事用ChatGPT、Copilot一键生成代码，提交评审时被leader骂得狗血淋头。

不是AI写的代码不能用，而是少了最关键的“说明书”注释和文档。

现在一半以上的程序员都在用AI写代码，可为什么同样的功能，有的人的代码被夸像艺术品，有的人的却被吐槽是“AI垃圾”？答案其实很简单，AI能写代码，但写不出你的业务逻辑，也替不了你的职业价值。

技术社区里有个叫Tacitus的开发者，最近快被客户逼疯了。

客户总用ChatGPT生成代码，然后发来“救命”请求，说交易机器人不工作了。

他跟进后发现，这些代码全是低级错误，要么访问不存在的端点，要么混用变量名。

客户自己看不出问题，觉得AI写的代码改改就能用，还要求免费支持完整应用开发。

这不是个例，我之前接手过一个离职同事的项目，全是Copilot生成的代码。

没有一句注释，我对着一个接口猜了一下午，才搞懂它是处理用户支付回调的。

后来紧急修复bug时，因为没摸清逻辑，差点造成资金损失。

AI生成的代码有个通病，它只懂“怎么做”，不懂“为什么这么做”。

它不知道你们团队的业务规范，也不清楚后续谁来维护。

这些信息只能靠我们自己用注释说清楚，不然再好用的代码，也会变成团队的隐形炸弹。

更有意思的是，有团队因为注释风格不统一吵到散伙。

有人用英文注释，有人用中文，有人只写功能不写逻辑，协作时光理解代码就要花半天。

国内团队真没必要硬凑“国际化”热闹，中文注释沟通效率才最高。

AI能搞定80%的标准化代码，那剩下的20%就是我们的生存空间。

这部分价值，恰恰藏在注释和文档里。

高质量的注释从来不是重复代码功能，而是解释“为什么这么做”。

比如函数头部说明作用、参数和返回值，复杂逻辑处讲清实现思路，关键参数解释选择原因。

本来想省点事少写几句，后来发现后续维护花的时间更多，完全得不偿失。

注释也不是越多越好，我见过有人写三行代码加五行注释，纯属画蛇添足。

一般来说，注释和代码比例控制在1:3到1:5之间最合适，关键地方点到为止就够了。

而且代码迭代时一定要同步更新注释，过时的注释比没有还坑人。

除了注释，文档更是AI时代的“第二大脑”。

字节跳动内部用的Rspress工具，能快速搭建文档站点，自动生成大纲和搜索功能，团队协作效率提升不少。

他们早就意识到，文档不仅是给人看的，也是给AI看的“上下文”。

现在很多团队开始搞“先写文档再写代码”。

把业务逻辑、设计思路写清楚，再让AI生成代码，这样AI能更贴合需求，后续维护也有依据。

我所在的团队就这么做，新成员上手时间从两周缩到了三天。

不同层级的程序员，对注释和文档的理解也不一样。

初级程序员只关注功能实现，中级程序员知道要写但质量不高，高级程序员会用注释传递设计思路。

很显然，能把注释和文档做好的人，才不容易被AI替代。

AI替代不了程序员，能替代的是只会写代码的程序员。

AI能生成功能，但生成不了你的思考过程；能写出代码，但写不出符合团队需求的规范文档。

这些看不见的东西，才是我们的核心竞争力。

代码是写给人看的，顺便给机器执行；文档是写给团队和AI看的，核心是传递不可复制的经验。

AI时代，注释和文档不再是软技能，而是硬实力，是我们的生存护城河。

与其担心AI抢饭碗，不如沉下心把注释写规范，把文档理清楚。

当你开始注重这些细节时，就会发现自己的不可替代性，编程之路也会走得更稳更远。

来源：冷秋月一点号