我偏爱短注释，偏爱长 Commit（代码提交记录）。代码要像门牌，让人一眼知道该进哪间屋；长注释却常像贴满墙的“此门已坏，请轻推”，不过是在替坏设计还债。真正该写长的，不是门上的废话，而是搬家单：为什么改，改掉了什么旧病，放弃了哪些路。这件事上，我的判断很硬：长注释常替坏设计还债，长 Commit 才保存决策。

不少人把“注释丰富”当作勤劳，把“提交记录详尽”当作仪式感。我看恰好相反。长注释往往像给骨折的人抹粉底，颜色很体面，站起来还是疼。长 Commit 则像病历，不负责让人看着舒服，负责让后来的人知道：这条腿为什么断，医生为什么不用上一种药。

反常识的地方在这儿：注释最擅长保存的，不是知识，是设计的失败现场；提交记录最擅长保存的，也不是动作，而是决策的尸检报告。前者解释“这段绕路代码别碰”；后者解释“为什么当初不得不绕路”。一个是在墙上贴便条，一个是在档案里存证词。前者治标，后者防止后人再犯同一种蠢。

我见过一个团队的支付模块，函数名叫“计算订单总价”，听上去像个老实人，点进去却像地下赌场。优惠券、满减、会员折扣、渠道补贴、退款抵扣，全挤在一锅里。作者显然心虚，写了二十多行注释，像在交代遗书：这里先这么算，因为历史原因；那里不要抽函数，因为另一个接口会炸；再往下看，还有一句最诚实的话，“不要轻易重构”。这不是注释，这是在门口挂护身符。三个月后，新同事改坏了线上逻辑，不是因为他没读注释，而是因为这套设计本来就该拆迁，不该装修。

也见过另一个场景。一个接口原本返回“状态码 0/1/2”，后来业务加出十几种异常分支，前端（网页界面代码）天天猜谜。有人终于动手，把返回值改成明确的状态对象，同时补了一条很长的 Commit：为什么不再沿用旧状态码；哪些调用方受影响；为什么这次不做兼容层；哪个监控指标会先抖两天。半年后，报警再起，接手的人没有去翻聊天记录，没有去问早已离职的人，只看那条提交记录，就知道当初是为了砍断哪条烂藤，愿意付出什么代价。那一长段话，不是文学创作，是时间留下来的口供。

还有一种场面更滑稽。夜里两点，线上故障，值班的人盯着一段注释：“这里必须先删除缓存，再更新数据库，否则可能出现一致性问题。”他说，既然注释都这么写了，那就照办。结果越修越坏，因为系统后来早就改成“先写数据库，再异步清缓存”，只是注释没死，像老房子里没搬走的灵位，还在指挥活人。第二天排查，真正救命的是两个月前的一条 Commit：某次事故后，为避免缓存风暴，更新顺序已整体调整。注释在撒谎，提交记录在作证。前者是墙上的旧地图，后者是河道改线的档案。

所以我不迷信“注释越多越专业”。在很多团队里，长注释其实是一种体面的遮羞布。因为改名字、拆模块、收边界，都要动真格；写一段注释最轻松，像往发霉的柜子里塞香包，闻起来不像问题，问题却更耐放。工程世界里最廉价的勤奋，就是给坏结构配一份深情说明书。

当然，注释不是原罪。好注释该像路牌，不像导游。它告诉你“这里为什么不能左转”，而不是陪你把整座城重新讲一遍。真正值得留下的注释，通常只有几种：解释为什么某个选择违背常识，说明外部约束，标出肉眼看不见的陷阱。它不是替代码翻译普通话，更不是替设计写悔过书。

而长 Commit 恰恰相反，它天然适合写长。因为提交记录面对的不是机器，是后来的人，是未来的自己，是那个三个月后已经忘了今天为何发疯的你。代码展示结果，提交记录保存理由；代码陈列尸体，提交记录交代死因；代码告诉你“现在是什么”，提交记录告诉你“为什么只能先这样”。这三句看似差不多，其实差着一整条责任链。

程序员有个常见幻觉：只要代码还在，历史就还在。错。代码只留下了胜利者的遗体，失败方案、权衡过程、当时的敌人，都埋在空气里。没有好的提交记录，团队的记忆就像城中村拆迁后的空地，地皮还在，巷子没了，老人搬走了，后来人只好凭想象画地图。于是同一类争论三个月轮回一次，同一种坑一年踩三遍，办公室里最稳定的基础设施，不是服务器，是遗忘。

我越来越觉得，注释和提交记录分属两种道德。注释是对“现在的阅读者”负责，所以应当克制，越短越要紧，像手术刀，不像棉被。提交记录是对“未来的协作者”负责，所以应当慷慨，越具体越值钱，像判决书，不像签到表。前者解决可读性，后者保存可追责性。把这两者倒过来，就会出现一种很滑稽的现代景观：代码里话很多，历史里话很少；眼前看似热闹，回头一问，全靠考古。

我甚至愿意把话说得再刻薄一点：
长注释，常常是设计没出息后的话痨。
短提交，是团队记忆力衰退时的装聋。
能被注释长篇解释清楚的问题，十有八九应该先被代码重写。
代码负责站住，提交记录负责作证。
注释写给“怎么读”，提交记录写给“为什么改”。

真正成熟的工程感，不是把每段代码旁边都配上散文，而是让代码本身尽量不需要翻译，让历史在该啰嗦的地方啰嗦到底。该改名就改名，该拆函数就拆函数，该补一条长提交就别省字。不要让后来的人对着一堵注释墙猜古人心事；要让他顺着提交记录，看见当时的路口、代价和胆怯。

我的立场很明确：宁可把力气花在改出不必解释的代码，也不要沉迷于给坏设计写墓志铭；宁可把字数留给 Commit，也不要把修辞浪费在注释里。
因为注释常常只是灰尘上的指纹，提交记录才是案件的笔录。

别人聊 AI，我们测 AI——每个结论都能下载原始数据自己复算。 🔗 官网 👉 https://crawdpad.com