AI时代，写注释反而成了高级技能

上周帮一个 junior review 代码，他写了三个月 Java，提交了一个三百行的 Service 类。代码逻辑没错，变量命名也规范，就是没有一个注释。

我问了一句，你为什么不加注释？

他说，AI 生成的代码不需要注释，代码本身就是文档。

我愣了一下。这话说得对，也不对。

注释的两个极端

程序员圈子里关于注释的争论，大概和”Vi 还是 Emacs”一样古老。

一派是《代码整洁之道》的信徒——Robert C. Martin 在书里写得很直白：注释不是对劣质代码的补救。他的观点是，与其给烂代码加注释解释，不如把代码重写到不需要注释。好的变量名、好的函数拆分、好的代码结构，本身就是最好的文档。

另一派是 John Ousterhout（《A Philosophy of Software Design》的作者），他认为注释是必要的，而且应该解释”为什么”而不是”是什么”。光靠代码本身，读者很难理解设计意图和取舍过程。

这两派其实没有根本矛盾。Bob 大叔说的”不需要注释”是理想状态，Ousterhout 说的是现实状态。大多数项目的注释问题不是多了还是少了，而是写的都是废话。

什么注释是废话

我见过最多的垃圾注释大概有这几类：

// 获取用户列表
List<User> userList = userMapper.selectAll();

// 循环遍历
for (User user : userList) {

    // 判断是否为空
    if (user != null) {

这种注释不叫注释，叫翻译。把 Java 翻译成中文，信息量零增加。如果这段代码需要注释才能看懂，那问题出在代码本身，不是注释不够。

还有一种更隐蔽的垃圾——过时注释。

// TODO: 优化查询性能，后续改用 Redis 缓存
List<Order> orders = orderMapper.queryByUserId(userId);

这个 TODO 在代码里躺了两年，Redis 也没人加。新来的同事看到注释，以为这东西马上要优化，结果等了半年发现没人管。过时的注释比没有注释更可怕，因为它给你虚假的安全感。

AI 写的注释，问题更大

回到开头那个 junior 说的”AI 生成的代码不需要注释”。他的潜台词是：既然 AI 生成的代码我都能看懂，为什么还要注释？

这个逻辑有两个漏洞。

AI 生成的代码”看起来”能看懂，但你不知道它为什么这么写。

比如 AI 生成了这样一段代码：

def calculate_discount(price, user_level, is_new_user):
    if is_new_user:
        return price * 0.7
    if user_level >= 5:
        return price * 0.85
    return price * 0.95

代码逻辑很清楚，一眼就能看懂。但你不知道的是：新用户打七折是运营定的临时活动，下个月可能取消；五级以上用户打八五折是因为年初的会员权益升级。

这些信息，AI 不知道，代码里也不会体现。如果不写注释，三个月后谁来改这段代码，根本不知道这些折扣背后的业务逻辑。

第二个漏洞：AI 写的注释往往也是翻译式注释。

你让 Copilot 或者 Claude 给代码加注释，它们大概率会生成类似这样的东西：

# 对新用户应用七折优惠
if is_new_user:
    return price * 0.7

废话。这种注释没有任何价值。真正有价值的注释是 AI 写不出来的，因为它需要上下文——业务背景、历史决策、团队约定。这些只存在于人的脑子里。

AI 时代的注释，到底该写什么

我觉得 AI 时代写注释的原则很简单：

只写 AI 写不出来的东西。

具体来说，就三类：

业务意图。 这个函数/模块在解决什么业务问题？这段逻辑对应的产品需求是什么？比如”这里的超时时间设为 5 秒是因为下游支付接口的 SLA 就是 5 秒，超过就要走退款流程”——这种注释值一千行代码。

设计取舍。 为什么选 A 方案不选 B 方案？为什么这里用了线程安全的数据结构而别处没用？”这里用 ConcurrentHashMap 而不是 HashMap 是因为这个配置会被多线程读写，参见 JIRA-1234 的线上 OOM 事故”——这种注释能让后人避开你踩过的坑。

非显而易见的约定。 “日期格式必须用 yyyy-MM-dd 而不是 yyyy/MM/dd，因为 MySQL 的默认日期解析会搞混这两个格式”。这种约定如果只存在于口口相传，一定会有人踩雷。

除了这三类，其他注释能不写就不写。代码本身的命名和结构应该承担”解释做了什么”的责任。

一个实际的做法

我在团队里推的一个注释规范，很简单：

每个公开的方法/函数，写一行注释回答**”为什么需要这个方法”**，不是”这个方法做了什么”。至于方法内部的逻辑，靠代码结构和变量命名去表达，不加行内注释。除非有特殊情况（比如某个魔法数字、某个 hack），才在局部加注释说明原因。

def calculate_order_discount(order: Order) -> decimal.Decimal:
    """
    订单折扣计算入口。新用户首单七折是 2026 年 Q2 运营活动，
    预计 6 月底结束（见运营文档 ORD-2026-042）。
    老用户折扣规则见会员体系文档 MEM-003。
    """
    # ... 实现

这一段注释，AI 写不出来。它包含了业务背景、时间约定、文档引用，是给人看的，不是给编译器看的。

重新定义”会写注释”

十年前，写注释是基本功。五年前，大家开始觉得”代码即文档”就够了。现在 AI 编程工具普及之后，很多人干脆连注释都不写了。

讽刺的是，AI 越强大，注释反而越重要。

因为 AI 让写代码变容易了，但理解业务逻辑、记住设计决策、传承团队知识——这些事情 AI 替代不了。当代码生成成本趋近于零，代码量指数级膨胀的时候，真正稀缺的不是”能写代码的人”，而是”能让别人看懂代码的人”。

所以下次你写代码的时候，不妨想想：这段代码半年后我自己还能看懂吗？新来的同事能理解我为什么这么写吗？如果能，不用注释。如果不能，写一句，只写为什么。

这不叫基本功，这叫专业素养。