从 TiDB 中学习代码提交规范的重要性

作者： RogueJin 原文来源：https://tidb.net/blog/7e9396d3

【是否原创】是

【首发渠道】TiDB 社区

【正文】

上几周开始，项目组成员结束每日站会后一个个都愁云满面，项目第一阶段都快交付了，项目组士气竟然如此低沉，项目肯定是要延期了。我明知故问道：你们项目遇到问题了？可怜的项目经理说，今晚又要加班了，上周修好的问题又出现了，这几个问题已经反反复复修了好几次了。其实看到他们在任务管理系统上的任务进展，我早就知道项目经理要说啥了，再看看代码管理系统中的代码提交情况，现在团队已经陷入反复修复问题的怪圈中，等这次回顾会议时候再给他们团队强调一下如何科学提交代码，这样他们才会印象更深刻些。

提交代码是一名程序员必备的工作技能，说的简单一些就是把本地完成的代码内容发送到服务器上，与其他团队成员的代码进行合并，一起完成一个系统的开发工作。

或许您已经是一名程序员了，可能会觉得提交代码这么简单的工作谁不会做，任何实习生都能在 IDE 里一键提交自己的代码，这还有什么需要讲的。如果这事讲到这里就结束了，那也就不可能有这篇文章了。顺便提一下这里的 IDE 是代码开发集成工具，大家应该都用过多功能刀具，一把看似普通的折叠刀具，可以瞬间变出各种工具，例如小剪子，锉刀，螺丝刀，啤酒瓶扳手，红酒开瓶器等等。IDE 就是类似的万能工具，针对开发过程中的不同任务场景，可以瞬间变出各式各样的工具去完成。

而对待规范代码提交这件事，初级开发工程师肯定会用感性思维分析给出一个答案，项目经理给我安排了一个任务，我用最快的速度完成了任务开发，我完成的任务越多绩效就会越好，那些对我完成任务没有任何帮助的工作，能不做就不做。但是一个没有自测过的代码提交，就如同没有做过检查的引擎直接装上了飞机，到底是想上天呢还是想飞上天全看上帝的脸色。又当需要查找过往代码修改历史时，上千个代码提交都写着一模一样的“修改代码”四个字，你肯定会如同大海捞针般抓狂 。

我们来看看一些代码提交不规范导致的常见问题：

• 代码没有注释。这是经常遇到的场景，突然某一天需要修改一段几个月前完成的代码，由于代码和业务逻辑复杂，再加上有多次修改，已经没人记得这些代码的含义了。最后只能重写，真是耗时耗力，项目拖延症的罪魁祸首。

• 没有单元测试。为了保证代码质量，一般会有程序员完成第一轮自测，我们称之为单元测试，主要正对单一逻辑代码通过容易导致错误的参数进行验证，整个过程都是自动的，能够解决大部分代码问题。没有单元测试保护的代码会增加测试工程师工作负担，严重的还会被测试工程师贴上代码质量极差的标签，拒绝测试你的代码。项目拖延症原因之二。

• 没有代码提交说明。代码提交时的说明是为了帮助程序员互相检查代码时提供方便，也为日后追查代码提供方便。而且现代 IDE 已经可以实时显示某一行代码提交者和提交说明，不规范的提交说明都会被打上难以合作的标签，更何况没有提交说明的程序员。这条伤害性不大，但是对自身侮辱性极强。

• 不按分支提交代码。项目发布有周期性，每次发布的功能都会在项目开始前规划好，代码分支管理在一定程度上就是来保证项目发布的。但是项目组经常会碰到不按规定提交代码的小伙伴，代码功能又不是这次发布功能列表中，代码还没被完全测试过，发布还是不发布，真是把项目经理的头发都熬白了。

所以相较于一个简单的代码提交来说，科学提交代码包含了几个内容：

• 针对一个开发任务的代码内容

• 易于理解的代码注释

• 相应的单元测试

• 规范的提交说明

• 按照代码分支管理规则合并代码

提交代码为什么要有这么多内容？

当然一个资深开发工程师会用理性思维思考这个问题。

第一步：项目分解之后会形成一个个小任务，任务之间是有相互关系的，不能认为单个任务是独立的个体，所以每一次代码提交都需要保证质量可靠。

第二步：团队成员之间也是有依赖关系的，每个成员的工作需要对个人及团队负责，需要保证质量的同时又必须能够回溯过程，也就是能够快速定位代码修改历史，修改所对应的原由，最后能够查到需求出处。

第三步：团队成员必须都遵守这个行为准则。

文字表述可能不够清晰，我们来一张对比图，看一下这两种思维的结果，左图是感性思维，右图是理性思维。哪一边更适合团队协作就一目了然了。

我们再来看看 TiDB 的代码提交流程，具体可以参考：community/README.md at master · pingcap/community (github.com)

首先写代码前先阅读 PingCAP 代码规范，代码不是想怎么写就怎么写的，每一个产品都有自己的代码风格，在下手前先要了解一下代码书写规范。PingCAP coding style guide | PingCAP Style Guide

代码写完要提交了，是不是很兴奋？且慢，先看看代码提交规范 community/commit-message-pr-style.md at master · pingcap/community (github.com)

你需要在代码提交注释中写明这些内容：

1. 你改了啥

2. 修改的目的

3. 你的代码会有什么影响

除此之外还有一堆规则，比如首行不能超过 70 个字、需要注明子系统、描述尽可能简洁等等，不要觉得审阅人能理解你的代码，这些都是帮助审阅人尽快通过代码审查的前提。如果是错误修复的代码还需要提供对应的单元测试，避免错误再次出现；如果是性能提升的代码需要提供修改前和修改后的性能测试对比报告。

这一切都完成之后还需要两名代码审阅人充分理解并确认你的代码之后才算完成一次代码提交工作。

科学提交代码初看上去效率很低，还做了很多额外的工作，甚至有些迂腐。但是，我们比较一下人类在科学发展上的工作，同样包含了很多看似低效无用的工作，例如论文引用，同行评议，验证实验等看似繁琐而且不近人情的规则，就是这些规则才保证了科学体系的健康发展。对于一个项目而言，工程师们的严谨也是保证项目健康发展的前提。

写完这篇文章差不多下班了，看看隔壁项目组，已经在会议室封闭开发快一个月了，估计今晚又要通宵了，希望这篇文章能够帮助到他们。

科学提交代码是技术大牛的必备素养！祝愿大家在通往技术大牛的路上越走越顺。