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

　　去年高考那几天，我带着三个新人蹲在机房改高考监控系统的代码——对，就是那种“考生抬头看摄像头三次就触发警报”的鬼东西。当时雨下得跟老天爷在倒水似的，外卖小哥举着塑料袋在走廊里喊“谁的黄焖鸡”，老张叼着烟在工位上敲键盘，烟灰掉在键盘缝里都没察觉。我原以为这种紧急项目肯定得乱成一锅粥，结果你猜怎么着？那帮人愣是靠“代码即文档”的规矩，把需求、逻辑、变更全塞进注释和命名里，连测试用例都直接写在函数头里——最后交付时，甲方翻代码找需求，比翻他们自己的文档还快。

文章配图，仅供参考

　　当然，这招也有翻车的时候。那天老李接了个电话，说“考生家长投诉警报太敏感”，扭头就在代码里把“抬头三次触发”改成了“抬头五次触发”，结果commit message里只写了“[监控]-[调整]-[家长投诉]”，没说明具体改了什么逻辑。下午测试时，监控系统直接漏报了三个考生抬头——后来一查，发现老李改的是“抬头次数”的阈值，但没改“连续抬头”的判断逻辑，导致系统只记录“单次抬头”，根本不触发警报。我当时气得直拍桌子：“你他妈注释里写清楚啊！‘修改抬头次数阈值从3到5，需同步调整连续抬头判断逻辑’——就多写两行能死啊？”老李挠挠头：“我急着下班接孩子，忘了……”你看，这就是“代码即文档”的软肋——它依赖人的自觉，而人总会有疏忽的时候。

　　但话说回来，这种“优胜劣汰”的机制，反而让团队更注重代码质量。因为代码是唯一“强制阅读”的文档，谁写得不清晰，谁就得被后续维护的人骂。去年我们接手一个老项目，原开发团队早散了，留下的文档全是“根据需求调整参数”“优化性能”这种废话，但代码里的注释却详细到“这个0.8是通过对1000组考生数据训练得出的最佳阈值，误差率低于5%”。后来我们改需求时，直接在注释里标“[2023.06.07]-[张三]-[因高考新规，将阈值从0.8调整为0.7，需重新训练模型]”，连测试用例都跟着改——这种“代码即历史”的写法，反而比什么版本控制文档更直观。

　　不过，这事儿也有个副作用——团队里开始出现“注释洁癖”。有人为了写清楚逻辑，在函数里塞了三百行注释，结果代码本身反而被淹没了；还有人为了“规范”，给每个变量都加前缀，比如“i_cnt_student_head_up”（学生抬头次数计数器），搞得变量名比代码还长。我后来定了个规矩：注释只写“为什么”和“边界条件”，不写“怎么做”——“怎么做”应该靠代码本身的逻辑清晰度体现，而不是靠注释。比如，与其写“// 这里用快速排序因为数据量大”，不如直接写“sort(students, key=lambda x: x.score, reverse=True)”——后者一看就知道是按分数降序排序，根本不需要注释。

　　现在回头看，“代码即文档”能站住脚，核心就两点：一是“强制阅读”——代码必须被后续维护的人看，而文档可能被忽略；二是“优胜劣汰”——写得烂的代码会被骂，写得好的注释会被夸，时间久了，团队自然会往规范的方向靠。当然，这招不是万能的——比如紧急需求、原型开发、探索性代码，这些场景下强行套“代码即文档”只会拖慢进度。但至少在稳定迭代的项目里，它比那些“写完了没人看”的文档管用多了。

　　对了，那天改完高考监控系统后，我们蹲在机房门口抽烟，老张突然说：“其实最狠的不是注释，是命名——好的变量名和函数名，本身就能当文档用。”我点头：“比如‘is_student_cheating’比‘flag’强多了。”他吐了个烟圈：“可有些傻逼就喜欢用‘a’‘b’‘tmp’，改他们的代码比看天书还难受。”我笑了：“所以啊，‘代码即文档’的终极形态，是让代码本身就能说话——注释只是辅助，不是主角。”

（编辑：站长网）

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