系统程序开发，注释写少了看不懂，写多了没人看，到底留多少才好？

代码注释不是越多越好，也不是完全不写。核心原则只有一条：注释只写“代码本身无法表达的信息”，尤其是决策理由、业务规则、潜在风险和变更约束。判断一段注释该不该留，就看删掉它之后，未来维护者是否可能会踩坑。按2026年项目交付习惯，多数成熟团队把注释重点放在“为什么”和“边界”上，而不是复述代码。如果你现在正被“不留注释看不懂，留了注释没人看”困扰，下面这套筛选方法可以直接拿去做团队规范。

注释真正要解决的三个问题

注释的目标不是提高“注释率”，而是降低未来修改代码时的认知负担。实践中，值得写的注释通常集中在三个问题上：

• 意图：这段代码为什么存在？它要解决什么业务问题？比如“这里要先查库存再加锁，避免超卖”就比“inventory.plus()”多了解释成本。
• 约束：哪些东西不能碰？比如“该接口依赖第三方超时时间，不能调到5秒以下”“这个字段与旧客户端兼容，不要随意改长度”。
• 状态：这段逻辑是临时的、废弃的、还是正在过渡？比如“过渡逻辑，下个版本随订单服务下线一起删除”能避免读者纠结。

这三个问题只要有一个回答“有信息”，注释就有存在价值；三个都“没有”，注释基本是多余的。

三问筛选法：一段注释该不该写

在项目里常见“每个函数都写注释，但真正复杂的地方没写”的情况。我们后来改用“三问筛选法”，写注释前先问自己：

1. 这段代码的意图能否从命名和结构直接看出？如果函数名叫calculateDiscount()，那“计算折扣”这种注释就是废话。如果函数名叫handleData()，那么解释一句“处理订单取消后的库存回滚”就非常必要。
2. 是否存在隐含的业务规则、兼容性约束或性能敏感点？比如“这个循环不能并行，因为共享同一个订单号”“这个字段值来自老版本迁移，空值要当‘未设置’处理”。这些信息不写注释，未来修改时容易踩坑。
3. 未来修改时，缺少哪条信息会导致返工或事故？这条问题尤其关键。如果答案是“不知道先扣库存还是先记账”，那注释就要写清楚顺序及原因。

按这个顺序筛一遍：只有第三问能明确回答“哪条信息”时，才值得写。这样写出来的注释，每一条都是决策点，而不是背景噪音。

常见注释类型对比：什么时候写，写多少

不同位置的注释承担不同职责。按项目交付习惯，通常可以这样划分：

• 文件/模块头注释：只在模块职责不清晰时写，说明它负责什么、不负责什么。不建议写作者、日期，这些交给版本管理。
• 函数/方法注释：公共接口必须写清楚入参、出参、异常和契约；内部私有函数按需写。典型长度是3~6行，能讲清“是什么、为什么、注意什么”即可。
• 行内注释：特别容易被滥用成复读机。建议只用在“代码顺序、边界条件、隐藏依赖”上。经验区间是每百行代码不超过2处，超过说明命名和结构可能有问题。
• TODO/FIXME注释：必须关联任务单号，否则三个月后就变成无法追踪的“历史债”。带日期的TODO也建议改成“版本+任务号”。
• 文档注释（DocBlock）：面向调用方，比如API参数说明。2026年常见做法是用OpenAPI或代码生成工具管理，手写的部分聚焦在“为什么不直接调用某现成工具”这类决策上。

对比一下极端的两种做法：完全不写注释，只靠命名和结构，适合一次性脚本或纯内部原型；关键业务代码里“决策注释”写得比较多，适合长期维护、多人协作。两种没有绝对对错，但中间态更容易失控——要么注释变成了复读机，要么代码逻辑改了注释还在说旧话。

注释的代价与反面案例

注释不是免费的。每行注释都要维护，错了比没有更糟。在项目里常见这样的场景：团队为了满足“注释率不低于30%”，给每个getter和setter都写了说明，但真正复杂的折扣计算逻辑只留了半行“// 算优惠”。后来又赶上商品策略调整，对接的同事对着代码猜了一下午，最后靠翻Git记录才还原规则。那一次返工，前后多花了3天。犀跃公司在后续几个交付项目里调整了规则：注释率不再作为考核指标，改为“关键决策注释覆盖率”。新增需求设计评审时，必须说明哪几处需要写“为什么”。验收时抽检：如果一处注释删除后，现场没人能说出这段代码的约束，就要求补充。按这个标准执行后，返工次数明显下降，代码评审也不再为“这句注释要不要删”吵架了。

注释验收标准：达到什么算合格

在代码评审和交付验收时，可以用下面5条快速核对：

• 删掉任意一行注释，代码读者是否还能知道“为什么不能反过来写”？
• 注释是否只解释原因、边界和业务规则，而不是重复代码本身？
• 关键流程（状态机、定时任务、异步回调）是否都有流程图或注释指向？
• 注释是否与代码同步更新？拒绝“注释说旧逻辑，代码跑新逻辑”的情况。
• 是否存在“为了写而写”的注释，比如“// 加1”“// 循环”这类？有就删掉。

这5条都是可操作的，不依赖主观感觉。如果团队能坚持几轮，注释就会自然收敛到“决策级”，而不是“描述级”。

适用场景与边界

适合：长期维护的业务系统、多人协作的公共模块、交接频繁的中台服务、需要对接外部客户的项目。这些场景里，注释属于沟通成本的一部分，该花得花。

不适合或不必上：一次性脚本、探索性原型、纯本地工具、代码量少于几百行且不会迭代的临时逻辑。对这些场景，花时间调整命名和结构比写注释更省事。如果你的团队连命名都没统一，先不要谈注释规范，否则只是给烂代码盖被子。

另外，公共接口的注释是API契约的一部分，缺了会影响联调效率；但内部实现的注释可以更克制。边界在于：注释应该服务于“修改安全”，而不是服务于“代码美观”。

常见问题

注释和文档注释有什么区别？

注释给修改者看，文档注释给调用者看。公共API的文档注释必须完整，内部实现注释只写“为什么”。

代码很直白，还要不要写注释？

如果代码逻辑一眼能看懂，就不写。但“直白”的标准是换一个不熟悉业务的同事也能看懂，而不是自己觉得直白。

注释里要不要写作者和日期？

不建议，交给Git记录更准确。日期和作者信息会过时，但“为什么”不会。

团队没人看注释，还写吗？

先解决代码是“谁在维护、多久维护一次”的问题。如果确实长期无人看，也不必硬写；但一旦有人踩坑，就要把那次教训补成注释。

命名写得好是不是就可以不写注释？

大部分“是什么”可以被命名替代，但“为什么”和“边界”命名表达不了。命名解决表面，注释解决因果。

行动建议：把“三问筛选法”贴到项目README或团队规范里，下轮迭代先试一周。重点不是消灭注释，也不是强制写满，而是让每一行注释都回答“删掉你会不会踩坑”。如果你的项目连命名都混乱，先从重命名和拆函数开始，注释规范可以晚一步。适用边界：长期维护的代码必须写决策注释，一次性脚本不用写。别让注释成为负担，也别让代码失去地图。