只有完美代码不够的，如何做一个完美的Pull Request？

点击上方 "Python人工智能技术" 关注，星标或者置顶

22点24分准时推送，第一时间送达

来自：公众号 读芯术 | 编辑：真经君

Python人工智能技术(ID:coder_experience)第216次推文 图源:unsplash

上一篇：「任性」的C语言之父：因拒付论文装订费错失博士学位，论文52年后重见天日

正文

想要提高团队绩效，找到瓶颈是第一步。现实中，最大的限制因素不是编码速度，而是代码审查。因此，为了加快审查速度，笔者对比了两种pull request：

·        注释很少并且快速合并的pullrequest

·        有很多注释，需要多轮审查的pull request

我的结论是，有九种方式能让审查pullrequest更轻松。

1.添加关于“为什么”的代码注释

在写一个新功能的时候，会有很多与之相关的信息。写代码时要全盘考虑需求，第三方系统的局限性，以及和遗留代码库的交互。但是别人不了解其上下文来源，所以看到这个代码时会问“它为什么在这？”或是“为什么要选择这种方法？”

因此要通过添加解释性的注释，让阅读代码的人提前知晓“为什么”。笔者不认同一些人宣扬的观点：注释有害，应当忽略。

注释有很多种类。那些描述代码用途的确实是累赘。提取一个方法，采用一个精心挑选的命名，就能消除这种麻烦。另一方面，当解释为什么这样写代码时，也增加了代码阅读者的信息量。这些注释将阅读者的认知水平理想化地提高到了与编码人员相同的层级，这有助于增进对代码的理解。

图源：unsplash

笔者的注释通常会给出类存在的原因、相关资源的链接以及代码的前因后果：

# First Crew Dragon launch was postponeddue to bad weather,
         # and now we needan event for the "second" first launch.
         # Hence the stupidname.
         classSecondFirstCrewDragonLaunch
          ...
         End

2.描述清晰

有关pull request的描述为审查者提供任务最初的上下文，包括：

·        标签的链接。

·        对已完成事件的总结（如果不能从pullrequest的标题中看出）。

·        相关pull request的链接（例如在另一服务中的相关变化）。

不要把自认为理解代码需要的信息放在对pullrequest的描述里，应当进行代码注释：它们的效果更加显著，有助于未来代码阅读者的阅读。

3.精简pull request

这是一项强大的技术，谷歌甚至就小型pullrequest的益处单独写了一篇文章（https://google.github.io/eng-practices/review/developer/small-cls.html）。以下是笔者最喜欢的小型pull request的特点：

·        审查更彻底

·        审查更快捷

·        更易合并（频繁的合并能减少冲突）

·        如果被拒绝，浪费的精力更少

以下办法能使小型pull request的编写更简单：

·        将重构提取到单独的pull request中

·        将大型功能分解（即使它们不是面向用户的）

·        学一些git小窍门很有帮助，把git add --patch和git rebase --interactive当成朋友

·        把长期运行的功能分支设置为pull request的目标，而非master的目标：

4.快速回应审查

处理审查注释通常比较费时，需要修复打字错误、添加遗漏的测试案例、对方法重命名等。如果你能快速完成，你的同伴就能花更少的时间来记忆与pull request相关的信息。

但这种方法的缺点是会增加上下文切换的工作量，替代方法是使用番茄工作法(Pomodoro technique)：每工作25分钟穿插一次短暂的休息。它能让人更专注、更有成效、更健康，并减轻疲劳度，休息后的上下文切换也会进行得更加自然。负面的破坏性影响虽然没有消失，但是会大大降低。

5.给自己的pull request注释

图源：unsplash

为某些变化（例如删除和重构）添加解释性的代码注释是没有意义的，应当考虑为自己的pull request注释，给审查者提供更多的上下文。

6.在创建pull request前重定新master的基准

这样做有很多好处：

·        测试可能在本地分支中会通过，但在应用的最近更新时会失败。

·        能够使用最新添加的功能（例如新的工具类）。

·        审查者如果没能找到近期的变化，就会感到困惑。

相比合并，笔者更喜欢重定基底，因为重定基底使得分支仅包含相关的提交。

7.不要修改经过审查的提交——要发送新的

要在单独的提交中处理审查注释，而不是修改或者除去更改。这样能够让审查者更容易核对在上次审查后发生的变化：

8.在实现功能之前讨论整体方法

这可以省下很多时间。在要处理更复杂的重构和功能之前，先与同事讨论一下方法。与其他的开发人员讨论，解释这项任务和你的想法，他们也许会表示赞成，也许会提出更好的方法。

很多时候笔者都面临着初步协调的缺失，好几天的工作成果白白浪费。想象一下你连续五天做一件事情，结果却听到“对不起，其实我们不需要……”想要把自己从失望中拯救出来，你得尽早获得反馈。

9.感谢审查者的建议

深刻地理解别人做出的改变并且提出有用的建议需要付出很多努力——请对于这一事实表达认同和感激。记住，代码的变化是短暂的——与队友的关系却是永恒的。

减少在代码审查上花费的时间，团队表现会很快得到优化，在下一次的pull request中运用这些小窍门，结果会大有不同。

--END--

往日热文：

喜欢本文的朋友们，欢迎长按下图关注订阅号Python人工智能技术

收看更多精彩内容

你在看吗？一起成长