代码即文档：逻辑清晰、规范至上的二十年实战法则

　　一三年那会儿，我跟老陈在西直门那个朝北的小屋里改CMS。窗户缝漏风，风扇嗡嗡响，他叼着烟把PHP模板里所有echo都换成short_tag——就为省那两个字符。我说这文档呢？他弹弹烟灰：「代码跑通了，就是文档。」当时真信。现在想想，那年我们连CI都没有，提交记录里写着“修bug”，实际是把支付回调逻辑硬塞进会员中心的if分支里。优胜劣汰？淘汰的是谁？是用户点支付页卡住三秒后关掉页面的那个瞬间。不是我们。

　　一七年改得猛些。开始带团队，租了阿里云两台ECS，自己搭GitLab。小王刚来，二十出头，蹲在我工位旁看我手写API注释，写一行，删两行。我说：“你记住，接口名必须带动词，返回字段别用缩写，比如‘usr_id’——这玩意儿三年后你自己都懵。”他点头，第二天就提了个PR，把所有‘usr_id’全改成‘user_id’，还顺手把swagger.json生成脚本加进hooks。我没拦。结果上线第三天，合作方对接人打来电话，说他们旧系统解析不了下划线，硬要我们改回‘usr_id’。我原以为规范能扛住业务压力，结果它第一个被拧弯。那天我默默回滚了，没让小王知道。这事我走错了——不该把规范当成钢尺，该当弹簧。弹回来的力，全砸在自己腰上。

　　桌上那台戴尔显示器，牌子记不清了。反正蓝屏过两次，第二次重启后，SVN客户端图标变成个问号。后来就再没用过SVN。这事儿和代码即文档其实没关系，但记得特别清。

　　二二年做内容中台，整个链路跑在K8s里，流水线自动校验接口契约、自动生成SDK、连Mock服务都是YAML驱动的。张工——就是当年在一三年帮我调MySQL主从延迟的张工，现在转做SRE，某天突然微信问：「你们现在是不是靠OpenAPI spec当文档？」我说是。他回：「那你们敢不敢把spec文件直接当合同发给法务？」我没回。真不敢。去年5月上线那个搜索聚合模块，接口文档里写着“最多返回100条”，实际代码里写了`limit 200`，因为上游缓存失效时补救用的兜底逻辑。没人敢改文档——改了就等于承认设计有缺陷。可代码早把缺陷刻进`search_service.go`第317行了。逻辑清晰？清晰得像刀子划开雾。规范至上？至上的东西，往往最先被业务绕过去。

　　李胖子前年卖了三个站，全靠采集起家。有一回饭局喝多了，他说：「你们天天写文档，不如我Excel里那个『标题清洗规则V3.2』管用。」说完把手机倒扣桌上，屏幕裂了道细纹。后来再没联系上。我存着他微信，备注还是“采集-标题去重”，没改过。其实他那套规则，比我们好多Swagger描述还准——因为每条都是用户真实点击跳失的数据喂出来的。文档不是写给人看的，是写给时间看的。可时间从来不读。

　　一七年那次错，让我停了一周没碰代码。每天早上八点到，泡杯茶，只干一件事：翻三个月前自己的commit，找那些写着「临时方案」「后续重构」的提交。数出来47处。其中31处，至今还在生产环境里跑着。它们不报错，不报警，只是每次新需求来，都得在旁边再贴一层胶带。胶带颜色越来越深。现在我们要求PR必须带「本次修改影响的其他模块」声明——结果90%的填写内容是复制粘贴的空格。不是懒，是大家都默认：文档再干净，也挡不住下次需求要用到那层胶带。

　　风扇还是响。老陈前年移民了，走之前寄来个U盘，里面是他整理的十六年老项目SQL dump。没说明文档，就一个txt：“user表id不是自增，是uuid_short()拼的，别用==比。”我打开看了三分钟，关了。没敢导进本地库。有些代码，你一旦读懂，反而不敢改。就像你突然看清一个人怎么活下来的，就不忍心教他怎么活得更好。

文章配图，仅供参考

（编辑：均轻资讯网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!