代码即文档：逻辑清晰、规范至上的12年实践

　　去年六月，主编在茶水间堵我，说“代码即文档”那篇稿子要日更，今天就得上线——我盯着他手里那杯枸杞泡到发黄的茶，心想这玩意儿又不是泡面，哪来的“即食性”。我原以为顶多补两段伪代码示例，结果他把PR链接甩过来，说运营那边刚测完原创度检测，三十七处雷同字段，全卡在变量命名上：user_id、order_no、timestamp……这些词它也敢标红？

　　空调滴水声又来了，嘀、嘀、嘀，每三秒一滴，正落在打印机旁边那滩没擦干的水渍上。老张端着麻辣烫进来，塑料盖掀开一股热气直扑显示器，我顺手把“逻辑清晰”那句删了重写，改成“if 你真想看懂这段，先去翻第十八行那个叫 validate_thing 的函数”。这句我敢打包票——我们组新来的小陈，上周三下午三点零七分，就是靠这句话在评审会上躲过三次追问。

　　可规范至上？呵。上个月底专题排期表下来那天，我正对着git blame看谁改了config.js里那个废弃的timeout字段，李工突然敲我桌面，嗒、嗒、嗒，跟打摩斯电码似的：“你猜审核驳回的理由是什么？”我没抬头：“是‘业务背景描述过于技术化’？”他摇头：“是‘未体现对平台生态的敬畏之心’。” 我愣了三秒，点开驳回批注截图，果然——就这一行，加粗斜体，下面还带个emoji蜡烛。我直接把整个commit message改成“谨遵生态指导思想，本次提交已注入敬畏感”，推上去三分钟后过了审。这个我说不准，但至少没再弹出蜡烛。

　　打印机又卡纸了。第三次。还是那张A4，印着《2024Q2技术传播合规白皮书（V1.2-终版-终版-终版）》，页眉被蹭掉半截，剩下“技术传……”。王总监路过瞥了一眼，说“你们这文档风格太硬”，转身就让实习生把所有函数名后面加个括号注释，比如get_user_info() // 获取用户基本信息（适用于B端C端及中台）。我就看着她一条条手敲，敲到第七十二个时微信弹进来一条群消息：“转载授权协议模板更新啦～请查收！”我点开扫一眼，附件名是《转载授权协议_V3_带水印_勿删水印_勿删水印_20240601_final_v2》。

　　说到优胜劣汰——去年六月那会儿，我们拆了个三年前的老模块，准备迁到新架构。拆到一半发现，里面二十一个函数，十三个连测试用例都没人敢删，因为没人能确认哪个还在跑。后来查日志，只有两个真活：一个是生成报表Excel的，另一个是凌晨三点触发钉钉告警的。其余十一个，全在Git历史里躺着，像十一具穿旧工装裤的尸体。我们没动它们。不是不敢，是怕一动，某个埋得比spring cloud还深的定时任务就突然复活——就像前天中午那台老服务器，没人碰它，它自己半夜三点十七分吐出一封1998年的HTTP响应头，User-Agent写着“Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)”。运维小刘蹲机房查了四十分钟，最后拔了网线。我原以为这是玩笑，结果他微信发我截图，底下备注：“真·裸奔二十年。”

　　所以现在我们组改标题，改一次不行，改三次。第一次叫《从零搭建高可用系统》，毙；第二次叫《如何让系统不挂》——主编说“缺乏方法论纵深感”；第三次改成《关于近期服务稳定性波动的几点归因与可落地的技术反思（附完整复盘checklist）》，过。你看，光“改个标题”：第一步删掉所有形容词，第二步补三个括号，第三步加一个“近期”限定时间范围，避免触发“内容陈旧”审核策略。而真正重要那段——为什么我们坚持用单例而不是依赖注入来管理缓存客户端——压根没人看。编辑KPI盯的是日更率和过审率，不是这段代码有没有被下游三百七十二次调用过。

　　上周五团建，喝多了，我说起这事，市场部阿哲插嘴：“我们连‘用户旅程图’都画成乐高积木块，你们写个if else还得配流程图？”我刚想反驳，前台小妹推门进来问：“老师，楼下有人送修电脑，说主板烧了，让技术负责人签个字。”我下楼看见那人拎着一台ThinkPad T420，键盘缝里嵌着半颗瓜子仁，正在拿镊子夹。我当场签了字，心里想着：这瓜子仁要是长进CPU焊点里，比我们去年写的那套“文档即代码”的命名规范还难调试。

文章配图，仅供参考

　　所以我下周打算干件事：把所有对外暴露的API文档注释，全部改成真实运行时输出的日志片段。不是mock，不是示例，就是生产环境凌晨两点的真实log——带traceId，带线程名，带当时redis里那个key的实际TTL值。可能被毙，可能被加个“需补充安全风险提示”，但至少，它不再是一段别人教你怎么读的说明，而是一段你自己不得不读的证据。至于能不能过审……我还没想好怎么填那个“补充说明”框。

（编辑：站长网）

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