写好提交记录：版本控制里最容易被忽略的细节

很多人用版本控制工具，只把它当成”存档”的工具：改完东西，随手敲一句”update”或者”fix”，提交了事。可过了几个月，当自己回头看历史，或者同事要搞清楚某行代码为什么这么写时，才发现这些提交记录几乎毫无用处，等于白存了，也白翻了半天聊天记录，找不着北，一头雾水，还越看越糊涂，越看越没头绪。其实，写一条清晰的提交记录，是性价比极高的习惯。

它到底有什么用

提交记录最直接的价值，是回答”这次改了什么、为什么改”。当线上出问题，需要回溯到某个时间点时，好的提交记录能让你快速定位；当别人（或未来的你自己）读代码时，它能解释当初的思路，而不是留下一个需要反复猜测、不断翻聊天记录才能弄明白的谜，白白浪费大家的时间和精力，还容易猜错，越猜越离谱，越猜越偏。

它还有一个常被忽略的作用：促使你想清楚自己到底做了什么。如果你连一句话都概括不清这次改动，很可能说明这次提交塞了太多不相关的东西，该拆成几个更小的提交。写提交记录的过程，本身就是一次自我梳理和检查，能帮你及早发现问题，而不是等到事后才懊恼当初图省事、贪方便、嫌麻烦、想快点收工，结果越省事越麻烦。

什么样的记录算合格

一个被广泛接受的结构是：先写一句简短的标题，概括这次改动；如果需要，再空一行，写更详细的正文，说明背景和动机。标题控制在一行之内，正文解释”为什么这么做”，而不是重复”做了什么”——代码本身已经说明做了什么，再重复一遍纯属浪费读者的时间和注意力，没有任何增量价值，也没有任何新信息，更没有任何新启发，纯属多余，画蛇添足。

内容上，尽量写清楚类型和范围。比如用”修复登录页的跳转错误””优化列表加载速度”这样的说法，比”改了一下”有用得多。关键是让任何一个读到这条记录的人，不用打开代码也能大致明白发生了什么，甚至能判断这改动大致影响哪些模块、波及多大范围、要不要担心连锁反应和潜在的副作用，心里有个底，不至于慌里慌张、没着没落。

几个常见的坏习惯

最典型的就是那种毫无信息量的提交：”update””修改””乱七八糟的改动”。这类记录除了占地方，没有任何意义。另一个极端是把一整堆无关改动塞进同一个提交，让人无法分辨哪些是为了什么，事后想单独回退其中一部分都做不到，只能连带着整锅一起端出去，非常被动，也非常容易出岔子、惹麻烦、留后患。

还有人喜欢在提交记录里写情绪或者流水账，比如”终于弄好了””改了好久”。这些对理解代码毫无帮助。提交记录是写给未来读代码的人看的，不是写给此刻的自己发泄情绪用的，分清这一点，记录的质量立刻就会有一个肉眼可见的、实打实的、让人眼前一亮的、让人刮目相看的、让人眼前为之一亮的、让人耳目一新的提升。

养成习惯并不难

不必一开始就追求完美。先做到一件事：每次提交前，花十秒钟想清楚”我这次到底改了什么”，然后用一句话写下来。坚持一段时间，你会发现自己的提交也变得更聚焦了，不再是那种大杂烩式的、什么都往里塞的一团乱麻，自己回头看也觉得清爽，别人读起来也不累，整个团队都舒服，皆大欢喜，事半功倍。

更进一步，可以把一次大改动拆成多个小提交。每完成一个逻辑上独立的小改动，就提交一次。这样历史会非常清晰，将来回溯或回退时也方便。版本控制的价值，恰恰藏在这些看似琐碎的细节里，而不在那些被反复强调、被写进无数教程和博客、被挂在嘴边的宏大概念和名词里，华而不实。

为什么团队里尤其重要

在一个人写代码时，提交记录差一点也许还能凑合；但在团队协作里，它就是共同的语言。同事接手你的代码、做代码评审、排查问题，都要靠这些记录来理解你的思路。写得清楚，别人省力；写得含糊，整个团队都要付出额外的沟通成本，效率也会被悄悄拖慢，积少成多就是一笔不小的、看不见摸不着但真实存在、也真实影响效率、真实拖累进度、真实耽误工期的损失。

很多团队会约定一套提交规范，比如规定标题要以什么动词开头、正文要包含哪些信息。这些规定看起来繁琐，其实是把大家的记录拉到同一个水准上，让历史变得可读、可检索。对团队来说，这是一笔回报很高的投入，长期收益远远大于一开始花在规范上的那点时间和精力，怎么算都划算，怎么执行都不吃亏，怎么坚持都值得，怎么贯彻都不亏，怎么落实都值。

工具也能帮上忙

写提交记录不一定要全靠手写。有些工具可以自动生成标题的雏形，或者在你提交前提醒你拆分改动。不过工具只是辅助，真正决定质量的，还是你对”为什么这么改”的思考。工具能搭把手，但代替不了这种思考，也替你想不清楚那些只有你自己才知道的背景和取舍，以及那些当时没有写下来的纠结、权衡和犹豫，那些才是真正有价值的东西。

说到底，提交记录是写给人看的，不是写给机器看的。只要始终记得这一点，多站在”半年后读到这条记录的人”的角度想一想，你写出来的东西自然就不会差。细节里见真章，这句话用在版本控制上再合适不过，也最容易被人忽略、被人不当回事、被人当成可有可无、无关紧要、无足轻重、不值一提的小事。