创建高效Pull Request的5点建议

2017-01-04 本文已影响993人豆志昂扬

代码评审是现代的软件开发周期中非常重要的一环，如果使用过Github 或 Bitbucket 源代码管理平台，合并请求(Pull Request) 对你应该不会陌生，合并请求是把功能分支(Feature Branch) 合并到主分支之前进行代码评审。

代码评审是软件开发进程中最耗时间，也是最难的部分之一，需要团队中经验丰富的成员参与阅读，理解和评估新功能的实现方案。

关于Git 分支经典模型可参看这篇文章传送门，

鉴于代码评审的重要性，在很多实践敏捷开发的团队中常规流程中都有“正在评审”栏目，让人烦恼的是该栏目下经常会堆积很多正在评审的请求。如何高效合理处理这些请求，加快项目进程成为困扰整个团队的难题，下面有一些建议关于如何创建一个优秀的合并请求，让沟通更高效和顺畅。

正视问题

首先我们必须承认评审合并请求是非常困难的，评审人的职责是确认被评审后合并代码是正确的且高质量的，作为评审人只能查看被修改文件列表和对比修改文件前后的不同之处，而评审人要理解该合并请求想达成的目标，具体采用什么方案，以及方案实施的如何，还要在评审中留意代码风格和打字错误等，更要尽可能在更高层面提出改善建议。

不了解代码评审的人总会疑惑评审人为什么会有很多事情要做，甚至有时候评审人面对大的合并请求竟然束手无策。作为申请者要如何才能让合并请求更容易评审呢？

我们不妨用产品经理的思维来观察合并请求这个产品，这时请求的评审者就是我们的客户，我们需要客户尽快购买(批准)我们的合并请求。理解用户在这个流程中会变的很重要，但这恰恰是请求申请者擅长的，因为绝大部分评审申请者都有做评审者的经历，不妨换位思考的想一想：“如何才能让合并请求对评审者更容易上手？”

等待通关的合并请求队列

为合并请求瘦身

让合并请求更简单是加快代码评审的最佳办法，因为合并请求较小，评审者很容易理解上下文和逻辑实现原因，尽快给出申请者想要的YES。

其实创建一个大的合并请求很容易，难的是如何把本应很大的合并请求拆分为多个小的组合。很多人都会过于专注于解决技术问题而看不到全局，在真正的项目中，解决技术问题在整个流程中只占到很小部分，从提出问题到发布产品到用户手里，需求分析、测试和发布都需要很多的时间。

所以不妨在项目开始时多花点时间把问题拆分到较小的范围，特别是团队正在被合并请求过多困扰的时候。相信我，这是值得的！

注：如何拆分大的合并请求为很多小的合并请求是很有挑战性的，有兴趣的可以参看这篇文章传送门。

有用的标题和描述

一个有用的详细描述对于高效地完成合并请求评审是很有帮助的，如同给合并请求瘦身一样有效。一个良好的描述需要满足以下两点：

帮助评审者遍历尽可能多的代码。
标记相关源代码文件并根据相关问题分组。

在描述的帮助下，评审者可以节省很多时间去阅读每一个文件从而确认熟悉相关概念，了解了相关概念后才能更容易的评估解决方案。作为相关文件的作者，是提供描述信息的最佳人选。同样地一个有用的总结性标题可以让评审者从更高层面认知合并请求，无论是标题和描述都应给评审者提供更多关于合并请求的上下文。

言之有物的提交信息

每一个Git提交都需要提交者提供相关信息，良好的提交信息也可以帮助评审者获取更多代码修改的信息，这对于小的合并请求特别有用。

一个优秀的的提交信息要满足以下5点：

包括做了什么修改和修改的理由。
不应包括如何做了修改，因为Git diff就可以得到相关信息，这里不用重复。
标题和主体之间用空行分割。
标题字数不要超过50，而主体每行字数不要超过72个。
在标题中使用祈使语气，如‘删除被废弃方法’、’发布1.0版本‘等。

注：关于如何书写良好的提交信息可以参看这篇文章传送门。

为合并请求添加注释

在你的合并请求中，是否存在文件相互依赖？有没有一个文件是包括了主要修改？这时不妨在文件内添加一些内联注释，可以帮助评审者尽快浏览你的合并请求。

注意，合并请求中的内联注释和代码中的注释是不相关的，在添加内联注释的时候，如果发现需要用注释来解释源代码，也许是你的源代码的确需要更多注释。

在合并请求发给评审者之前，如果可能不妨为创建一个准合并请求，可以在自己进行评审时，在一些感兴趣的地方添加注释。

视觉化

如果合并请求是关于前端修改，可以添加一些截图。截图可以让评审工作更简单，通过截图评审者可以视图化地发现请求中了做了哪些修改。如果有必要，可以使用GIF文件或小视频来替代图片。

可以考虑邀请设计师参加评审，设计师通过截图很容易发现不一致的地方，是否有复制粘贴的错误等。当然和设计师沟通也可以通过其他渠道进行，但图片和视频总可以让沟通更有效。

总结

如果你认为合并请求是一个产品，申请者是销售人员，评审者是客户，这样你会想尽一切办法地'销售' 你的合并请求，尽快得到客户的批准，而上面介绍的五种改善合并请求体验的思路，只是加强‘销售’的一个方面，如果你有其他更好的办法，欢迎留言分享给大家。

获取更多内容请关注微信公众号豆志昂扬:

直接添加公众号豆志昂扬；
微信扫描下图二维码；