Google代码检视指南-Code Review Developer Guide(译)

本文译自Google发布的代码检视指南，仅为个人理解，不代表任何官方，不准确的地方欢迎指正，原文路径：https://google.github.io/eng-practices/review/

Code Review Developer Guide

How to do a code review

Code 检视的标准

代码检视的主要目的是确保代码库上所有的代码保持健康，并且持续改进。所有的工具和流程都是为了这个目标设计的。

为了达到这个目的，很多地方是需要权衡的。

首先，开发者必须保持任务的进度。如果你从来不合入任何改善的代码，那代码库就不会有任何改善。当然，如果一个检视者很难对任何变更进行合入，那么开发者也就没用动力在将来进行任何改善。

另一方面，保持代码库的健康和质量不下降，是每个检视者的职责。这挺难的，因为往往整体质量的下降，是因为一笔笔小的降低质量的合入导致的，特别是团队在时间紧迫的时候，他们会认为走捷径才能打掉目的完成任务。

一个检视者也对检视的代码有责任和所有权。他们希望确保代码库是持续设计一致的、可以维护的、以及其他有关"在检视中应该关注什么"一节中提到的其他内容。

从而，我们得出我们希望在代码检视中遵循的规则是：

正常情况下，如果提交的代码比库上的代码有所改进，即使不是完美的，也应该合入。

这是整个代码检视指导的最高原则。

这当然有些例外条件：如果新增的特性设计的不是很好，或者这个代码不应该在此时出现，那也不应该合入。

关键在于，没有所谓完美的代码，检视者不应该在代码合入之前要求把每个细节打磨的很好。相反，相比不断提出改进意见，检视者更应该关注代码提交合入带来的进度不断推进。与其追求完美，不如追求持续的改进。只要一个提交对系统的可维护性，测试，可读性等方面有所改进，就应该毫不犹豫的合入他们，而不应该消耗太久的时间追求完美。

检视者，应该持续的去提示哪里做的更好，但如果是无关紧要的事情，可以加一些前缀让提交者忽略。

指导

代码检视活动始终是对开发人员学习新的框架、语言、软件设计原则和知识是有益的。分享知识也是不断提升代码质量的方法。如果你的想说的意见只是纯粹的教育，或者是本文档中提到的原则之外的东西，还是不要写到检视意见里了，或者加上Nit的前缀，让开发人员知道这不需要关注。

原则

• 始终要以科学事实和数据为依据，而不是观点和个人偏好。

• 样式相关的问题，以样式指南中的为权威。任何指南之外的东西，比如空格，以个人喜好为主，但是要保持一致。如果之前没有过类似的，那就以提交者的为准。

• 软件设计方面的问题，从来不只是样式或者个人喜好的事情。不能只看个人喜好，必须是基于基础的设计来评估。有时候看起来是合理的做法，如果提交者可以说明这些基于数据或者固定的设计原则的合理性，也应该通过提交。其他情况都应该基于标准的软件设计原则。

• 如果没有其他可用的规定，只要不恶化，应该和现有库里的设计保持一致。

解决冲突

首先应该基于本文达成共识。当达成一致变得很困难时，应该面对面沟通，而不是就在评审意见上聊。讨论的结果应该补充到意见上去。如果解决不了就应该找渠道上升问题，但是要围绕提交本身讨论。

代码评审应该关注什么

注意，关注以下几点的时候，应该时刻牢记代码检视的标准。

设计

提交的整体设计是否合理？提交的各个代码片段之间是否交互合理？提交的代码位置对不对？现在是添加这些功能的时候吗？

功能

代码是否代表开发人员想做的？可以给使用到这段代码的用户带来什么好处？有时候这段代码的用户就是他们自己。

大部分时候，代码应该是经过开发人员充分测试的。然而，检视者应该在审核的时候也按照用例去思考，通过看代码发现并发的问题，站在用户的角度上考虑，发现一些BUG。

如果需要的话，需要验证提交的代码，有些对于用户可感知的功能尤其重要，比如修改UI的代码。你可以要求开发人员提供demo，因为这种代码仅仅通过阅读是很难看出来实现的对不对。

另外一个更重要的是提交的代码里有没有并发的部分，这种BUG很难在运行时发现问题在哪。这也是要求如果有可能会导致资源竞争和死锁问题的时候，尽量不要用并发模型去编写代码。

复杂度

提交是不是比预期更复杂？需要从几个角度去评估：代码行是不是太多，方法、类是不是太复杂？太复杂意味着无法通过阅读很快的理解代码，而且调用和修改他们的时候，很可能引起BUG。

还有一种特殊的复杂度是过度设计。通常是开发者希望这代码比实际需要变得更通用，或者添加当时系统不需要的功能。检视者尤其要警惕这种情况，鼓励开发人员只解决当下需要解决的问题。而不是去解决那些猜想未来可能发生的问题。问题来的时候应该马上解决，你会看到问题真真实实的出现在面前的。

测试

提交应该经过了适当的单元测试或者端到端测试，有些时候也应该包含测试用例一起提交。除非是在解决紧急问题。

确保测试用例是正确、可靠、有用的。测试用例没法测试自己，我们也很少对测试用例写测试用例，我们应该保证测试用例是对的。

代码错误的时候测试会报错吗？每个测试用例都有正确而且有有效的断言吗？每个用例都是独立可靠的吗？

记得测试用例也是需要维护的，不要认为他们不会打到包里，就允许让用例变得太复杂。

命名

代码每个部分的命名是正确的吗？是不是足够长到可以描述清楚这个东西是个啥或者要干啥，如果命名太短可能没办法讲清楚。

注释

开发人员是不是用可以理解的英文(文字)写了清晰的注释？这些注释是必要的吗？通常来说，注释应该描述的是为什么代码要这么写而且写在这，而不是代码在做什么。如果代码没办法清晰的自注释描述自己在干嘛，那么这代码应该变得简洁点。但是比如算法或者正则表达式类的注释是例外，应该描述清楚在做什么。其他大部分情况应该描述一些代码本身无法承载的信息，比如讨论结论等信息。

查看这提交之前的一些注释也有所帮助，比如修改意见或者TODO之类的。

注意这里说的注释不是文件、类、方法头的文档注释，那些是用来描述代码模块的功能以及使用后起什么作用的。

风格

Google所有主力语言和大部分一般语言都有风格指导，确保开发人员已经遵守了风格规范。

如果你想提升一些风格规范里没提到的点，那最好在注释之前加上Nit，以说明这个不是强制的，只是更好的改进意见。不要因为个人的偏好阻塞提交的进展。

提交变更的人不应该修改主要风格，不然会让人很难理解代码本身的变更，会让merge和回退变得更复杂，还带来其他问题。比如说会有单独的代码格式化提交，然后另外又有真正的修改提交。

文档

确保提交代码关联的文档及时刷新，包括ReadMe等以及其他相关的文档。如果提交删除或者废弃了一些代码，确保文档也同步删除。如果提交者遗漏了文档，提醒他们。

每一行

要去看分配到检视的每一行代码。有些诸如数据文件、生成代码、大的数据结构体可以一扫而过，但是手工写的代码不行，也不能假设那里面的代码是对的。明显有些代码应该非常仔细的阅读，但是必须要确保你真正理解了他们都在做什么，这种能力是需要锻炼的。

如果很难进行检视，而且当时很忙，应该告诉开发者，让他进行代码讲解后再检视。你也是我们在Google雇佣的非常优秀的程序员之一，如果你都无法看懂，其他人也一样。所以当你让开发人员讲解的时候，也让其他人一起能懂了。

如果你觉得还有一部分代码自己没资格检视，一定确保有资格的人要来检视，比如安全、并发、国际化等方面。

上下文

通常来说，如果能看到更多的上下文，这对代码检视很有好处。一般情况下，代码检视工具都只是展示变更的那几行。而有时候你需要查看完整文件以确保变化的部分是合适的。

从整个系统角度思考上下文也很有帮助，比如提交是让整个系统更好了吗？还是更复杂了？绝对不要让那种降低代码质量的提交合入。事实证明，质量恶化都是一笔笔小的恶化的提交共同造成的。

好的代码

如果你发现有一些部分做的很好，告诉他们，特别是可以通过意见表示。检视者们通常只关注错误，但是我们也应当对好的实践给予鼓励和感谢。作为引导者，有时候告诉他们哪里做的好，比哪里做的不好更有价值。

总结

在检视的时候，应该确保以下方面：

• 代码是设计合理的

• 代码的功能对用户是有价值的

• 任何UI的改动应该是正确合理的

• 任何并发的编码都是不安全的

• 代码不能太复杂，尽量简洁

• 不能为了尚未出现的东西，而现在也不知道会不会出现的东西而去实现

• 代码应该经过充分测试

• 测试的设计也是合理的

• 所有命名应该清晰合理

• 注释应该清晰有用，而且应该解释清楚为何这样做更好

• 代码和文档应该保持同步

• 代码风格要和风格规范保持一致

确保每一行代码都检视到了，结合上下文，确保代码质量有所提升，并且做法很好的时候，应该赞扬他们。

在提交里切换检视(Navigating a CL in review)

现在你知道了在检视中应该关注什么，那么在检视过程中，如何能有效的在提交的诸多文件里切换呢？

1. 这次变更看起来合理吗？变更描述是否写得好。
2. 先看一下提交里的重点部分，设计是不是合理。
3. 按照合适的顺序检视剩下的文件

第一步：先看一下变更的整体情况

看一下提交注释，以及变更整体上做了什么。这次变更是合理的吗？如果这次变更不应该出现，尽早反馈给开发者，并且告知为什么这时候不应该发生这样的变更。当你拒绝了这类提交的时候，更好的做法是建议开发人员什么样的做法更好。

比如说这样说：“这做法看起来不错，然而，我们正在重构，马上会删除FooWidget这个类，而正好你还修改了，我们不希望这会还有新的变更。不如试试新的BarWidget类咋样？”

注意，这不仅仅是在拒绝提交的同时给出了替代方案的建议，关键是这很礼貌。这种态度非常重要，因为我们展示出了我们态度，即使我们不同意某些做法，但是我们任然很尊重开发者。

如果你发现有好几笔提交都不对，那你应该确认下团队的开发进度如何。避免开发人员完成大量的工作后返工或者需要大量重写，应该在启动工作之前尽量避免开发人员做无用功。

第二步：评估变更的主要部分

找到变更列表的主要文件。通常，逻辑变化最多的文件就是这次提交中的主要变更。先检视这些主要变化。这对检视其他小的变更点提供了上下文信息的帮助，而且有利于提高检视效率。如果很难从提交里找到主要变更，让开发人员告知你应该先看哪里，或者让他们把提交拆分成多次提交。

如果你发现有严重的设计问题，即使你现在没时间检视剩下的代码，应该尽快把这个情况告知开发者。实际上检视其他代码可能是浪费时间，因为设计问题足以表明一切，其他变更都是无关紧要的。

有两个主要原因表明应该立即把这些设计问题告知开发者：

• 开发者通常提交代码后，马上会基于这笔代码继续下面的工作，马上告知他们也避免了做无用的工作。以免在错误的设计上继续做工作。

• 重要的设计变化会比普通修改话更多时间，开发者又有deadline，需要今早对这些重要的设计变更启动修改。

第三步：按照适当的顺序检视剩下的文件

当你确认没有重要的设计问题时，就可以看看剩下的文件了，确保不遗漏的按照一个合适的顺序检视其他文件。通常来说，如果主要文件没有问题，按照检视工具的顺序，检视其他文件也不会太难。有时候先检视用例也很有帮助，因为这能让你知道这些代码是为了做什么的。

检视速度

为什么检视代码速度应该很快？

在Google，我们持续优化开发者在一起完成产品开发的速度，而不是单个开发者的效率。个人的速度是很重要，但是比不上整个团队的速度。

如果检视的很慢，有些问题就会暴露出来：

• **整个团队的速度就会变慢。**当然，对于个人来说，如果不去快速响应代码检视，就能做很多其他事情。然而，如果这样的话，其他团队成员的新特性、bug修复就会因为等待检视而耽误很久。

• **开发人员开始抱怨检视进度。**如果检视者几天才响应一次，但是开发者的提交每次都很重要，这对开发人员来说会导致泄气和感到困难。通常，这会让开发者认为检视者有多么的严格。如果检视者经常快速响应开发者提交的变更和更新，而不是只管自己提交大量代码，投诉就会慢慢消失。大部分关于代码检视的投诉都会因为快速响应而消失。

• **会影响代码质量。**当代码检视的很慢的时候，会让开发者提交没那么好的代码。慢的代码检视，也会导致开发人员不会积极的去做重构、让代码更清晰，和去做为未来着想的更好的特性。

代码检视应该多快？

如果你没有正在做需要集中精力的事情，你应该在检视到来了的时候尽快处理。

代码检视应该在一个工作日内被处理完成（或者第二天早晨的第一件事）.

遵循这些准则，意味着正常的代码应该在一天内被检视好几轮。

速度 vs 打断

有一种情况，个人效率要比团队效率更重要。就是**如果你正在处于需要集中精力的工作时，不需要为了代码检视而打断工作。**研究表明，一个人的心流需要很长的时间才能从被打断的工作中恢复。所以，打断你自己的工作所要付出的代价，比让其他人稍微等一会要高的多。

换言之，你可以在有阶段性工作完成的时候，再去响应代码检视的请求。比如吃完午饭、会议结束、阶段性编码结束的时候。

快速响应

我们讨论的速度，是指响应时间，而不是花了多长时间把整个提交看完然后合入。理想情况下，整体检视也应该很快，但是对于反馈给个人的快速响应，要比快速的把所有文件都看完来得重要。

即使有时候需要很长时间才能检视完整个代码，如果在检视过程中可以持续到给到开发人员响应，也能缓解等待带来的焦虑感。

如果现在忙的没法很快响应代码检视，也应该告知提交者什么时间可以处理，或者转给他检视者处理这笔提交，或者先提供一个整体的检视意见。

更重要的是，检视者应该花费足够的时间对代码检视，以保障代码符合我们的提交标准。理想情况下，应该尽可能快的给开发人员回应。

有时差的检视

尽量在开发人员还在办公室的时候反馈意见，或者确保他们第二天一上班就能看到检视意见。

检视意见中的LGTM(Looks Good to Me)

为了提高检视速度，检视者也可以在检视意见没有完全修复的时候合入代码。但是仅限以下情况：

• 你对开发人员有信心，他们会修复剩下所有的检视意见。

• 剩下的变更都是次要的。

检视人员应该指定他们合入的时候是以上哪种情况。

开发人员有时差的时候，在检视意见里增加LTGM也非常有价值，这样开发人员就不用等一天，就为了LTGM/合入。

大量的提交

当你收到了一大笔提交，而你又无法确定什么时间可以处理完，你应该让提交者拆分成小更小的提交，而不是一次性检视完。即使这可能会花费些功夫，这对检视人员也非常有必要和有帮助。

如果提交无法拆分，而你也没办法快速完成所有的检视，那应该提出一些整体设计的意见，返回给开发者继续改进。作为一名检视者，你的目标之一是在不牺牲代码质量的前提下，不要阻塞开发人员或者让他们尽快的采取下一步行动。

代码检视的持续改进

如果按照这个指导要求检视者，并且严格执行，你会发现代码检视变得越来越快。开发者学习到了如何使代码质量变好，并且一次性可以做好，需要检视的次数越来越少。检视者掌握了如何快速回复，并且在检视过程中减少不必要的等待时间。但是不要为了速度而牺牲代码质量，长远来看，这并不会提升检视效率。

紧急情况

确实有些时候，整个提交需要快速的合入，而且往往是放宽质量要求的地方。关于这点，请参考“什么是紧急情况”的描述，以确定什么情况是真正的紧急情况，而什么不是。

紧急情况

有时候，代码提交需要尽快的合入。

什么是紧急情况

紧急情况的提交需要很小：不允许回滚的重大发布、生产环境的BUG修复、处理法律相关的问题、修复安全漏洞等。

紧急情况下，我们尤其要注意整个提交的检视速度，而不仅仅是响应速度。仅仅在这种情况下，检视者需要特别关注检视速度和代码的错误(这真的解决了紧急的问题吗？)。当这种提交过来的时候，应该优先于其他任何提交。

然而，紧急事情解决后，需要再回过头来再次检视代码，关注一下代码检视的其他部分。

什么不是紧急情况

要清楚的是，这些情况不是紧急情况：

• 想要在本周而不是下周完成
• 开发人员已经做了很久了，他们真的想尽快得到合入
• 开发人员全都有时差，而且现在是深夜或者他们都在外场
• 现在已经是周五了，仅仅是为了周末离开之前完成
• 管理人员要求开发人员在今天soft（not hard） deadline之前完成
• 导致出包失败的回滚提交

等等等等

什么是硬性的Deadline

如果错过了时间，会损失惨重，才叫做Hard Deadline，例如：

• 为了履行合同而必须完成的提交

• 如果错过这次机会，你的产品会在市场上遭到失败

• 有些硬件每年只更新一次。如果你错过了，将需要花费非常大的代价去更新的代码。

影响到周构建的日期不是致命的，但是影响到重要会议可能是致命的，但一般情况下不是。

大部分Deadline是soft的，不是hard。他们表示希望能在某个时间之前完成，他们是重要的，但是你没必要为了牺牲代码质量而满足他们。

如果你有一个很长的迭代周期（比如几周一个），可以有机会在下次迭代开始之前牺牲部分代码检视的质量完成某些功能。然而，这种情况下，如果重复出现，团队会积累大量的技术债务。如果团队总在迭代末期提交大量的代码而无法充分检视，那么团队应该修改流程，让大特性早点启动开发，并且得到充分的代码检视。

怎么写检视意见

摘要

• 礼貌一些

• 解释原因

• 注意只是说清楚问题，让开发人员自己去选择方案

• 鼓励开发者用更简单的实现或者添加代码注释，而不是只给你一个人解释复杂度

礼貌

通常来说，礼貌和尊重，对你检视的代码的开发人员非常重要而且有帮助。有一种方式可以确保你这样，就是注释只是针对代码，而不是开发者本人。你不一定要牢记这个要求，但是你要很清楚的是，当你在说什么事情的时候，有可能会引起争议，比如：
BAD：为何你要使用多线程？这很明显对性能没什么帮助？
GOOD：多线程模型会增加系统复杂度，而这里使用我看并不会带来性能提升，这里最好用单线程处理就行了。

解释为什么

有件事你得注意，上面GOOD的例子，会帮助开发者为什么会给这样的意见。你不一定每次意见都包含这些提交，但是有时候适当的多解释一点你的意图，和你的最佳实践、或者你的意见会帮助代码如何变得更好。

给予指导

一般来说，修复提交是开发人员的责任，而不是检视人的。你不需要详细的描述设计，或者帮他们写代码。

这不是说检视者就没啥用了。一般来说你得在只指出问题和给出直接的答案之间平衡。只指出问题后，让开发人员自己选择方案，能让开发者自己成长，也能让检视越来越轻松。这也是可以得出更好的方案的，因为开发者是最接近代码的人，而检视者不是。

然而，有时候直接的方案、建议甚至代码也很有用。检视的最重要目的是让提交变得更好，第二个目的是提升开发者的技能，让检视的需要变得越来越少。

接受说明

如果你让开发者解释那些你不懂的代码，通常应该让他们更清晰的重写代码。偶尔的，在代码里添加注释也是合适的，只要是不是为了解释过于复杂的代码。

仅仅是在代码检视工具里解释说明，对后来的代码阅读者没有好处。仅仅某些情况可以接受，如你在检视的代码不是你所擅长的，而这些说明其他检视人已经了解了的信息。

处理被拒绝的意见

有时候，开发者会拒绝检视意见。要么是不同意建议，要么是他们觉得你的要求太严。

谁是对的？

当提交者不同意你的意见，首先考虑下他们是不是对的。通常来说他们比你更接近代码，所以他们可能在某些方面有更好的意见。他们的讨论看起来合理吗？这看起来对代码质量有好处吗？如果是的，让他们知道这是对的并且抛弃检视问题吧。

然而开发人员不总是对的。这种情况下，检视者应该更多解释为什么坚持自己是对的。一种好的办法是既要理解开发人员的解释，也要附加更多信息表明为什么要怎么修改。

特别的，当你认为你的意见可以提升代码质量，你应该继续倡导这个提交，如果他们相信需要更多的提交来提升代码质量，就应该持续做下去。提升代码质量通常会经过小的提交。

有时候解释建议会花很多轮，但是只要确保礼貌，并且让开发者知道你理解他们想表达什么意思，只是你不同意而已。

烦躁的开发人员

检视者通常认为开发者会因为检视者坚持一些改进而沮丧或者烦躁。有时候开发者会变得烦躁，但是通常来说，过段时间他们会感谢你帮助他们把代码搞的更好了。通常来如果你在意见里保持礼貌，开发人员也不会变的烦躁。烦躁经常是因为检视意见的写法，而不是因为坚持在某些代码质量上。

稍后清理

一种常见的拒绝意见是因为开发者理解了，但是他们想马上完成任务。他们不想再来一轮补丁提交，所以他们说他们会稍后把检视意见处理了，这时候你应该合入提交。有些开发者非常善于这样做，他们会马上提交一笔修复意见的代码。尽管经验表明，在第一笔上提交的越多，这种修复的提交就越少。而事实上，如果不是马上修复，通常也就不会再修复了。这不是说开发人员是不负责任的，而是因为他们有太多工作要做，修复意见会因为其他事情而忘掉。因此，最好是在代码完成之前合入库里之前，坚持开发人员马上修复他们的提交。放任开发者说“稍后完成”，就是放任代码库退化。

如果提交表现出新的复杂度，这些代码必须在合入之前修复，除非是紧急情况。如果提交暴露了周围的问题，而现在又没法修复，那开发人员应该给自己提交一个BUG以跟踪修复。也可以在代码里加上TODO注释。

关于严格要求的投诉

如果你以前很宽松，突然变得很严格，那有些开发人员会大声投诉的。提高检视速度通常会减少这些投诉声音。

有时候，会花费几个月让投诉消失，但是最终开发者会看到严格的检视带来的价值，如他们所见他们是帮助生产这伟大代码的一员。有时候，叫的最厉害的人，在看到严格要求带来的好处后，反而会成为最支持的人。

解决冲突

如果你遵循以上指导，但是任然和开发者有冲突无法解决，看一下“代码检视的标准”以及原则，将有助于化解冲突。

The Change Author’s Guide

这份指南帮助你快速高质量的通过检视。

• 编写一个好的提交说明

• 更小的提交

• 怎么处理检视意见

编写一个好的提交说明

提交说明是一个公共的记录，里面说明了变更做了什么以及为什么变更。这是我们版本控制的一部分，不只是检视者，未来很多人都会看到这些记录。

未来的开发者会基于描述搜索提交。因为时间太久记不起来，将来会有人来看这修改了什么。如果所有的信息都在代码里而不是提交说明里，这将给找到这笔变更带来很大的困难。

第一行

• 简要说明这是在做什么

• 用完整的句子，用命令式语言说明

• 空行

描述的第一行应该是简短的说明这笔提交做了什么(What)，然后跟着空行。这一行是将来查找代码的人员在浏览版本控制系统的时候看到的，所以第一行应该有足够的信息可以说明这笔提交做了什么，而不需要看详细的描述和代码。

传统意义上，第一行应该是完整的命令式语言（势在必行的句子），比如说，“删除RPC调用并替换为新的系统”，而不是“删除了RPC调用并替换成了新的系统”。不过，不需要把其他部分也写成命令式语言。

For example, say "Delete the FizzBuzz RPC and replace it with the new system.” instead of "Deleting the FizzBuzz RPC and replacing it with the new system.”

详细描述部分应该有足够的信息

描述的其他部分应该包含足够的信息。可能包含要解决问题的简要描述，为什么这样做最好。如果这种方法有缺点，这时候就应该被注意到了。如果有相关信息，可以包含诸如问题数量、结果、设计文档等背景信息。

甚至对于小的提交，也应该注意一些细节，比如把相关提交写的描述里。

不好的描述

“修复问题”是信息不足的描述，什么问题？做了什么修复的？其他类似的不好的描述诸如：

fixbuild/添加补丁/把代码从A移到B/第一部分/添加工具类/删除奇怪的URL

这些都是真实的描述。他们认为提供了足够的信息，但是他们没有达到于提交描述的真正目的。

好的描述

功能性提交

rpc：删除RPC服务器端消息列表限制

类似FizzBuzz的系统有大量的消息，而复用消息示例带来性能提升。把freelist变大，并且持续的添加指向释放列表的指针，这样空闲的服务器就可以释放整个消息队列实体。

开始用少量语言描述了这个提交具体做了什么。其他部分描述了修复了什么问题，为什么是好的解决方案，并且附加了一些信息。

重构

使用TimerKeeper构造一个任务，以使用TimStr和Now方法。

给Task添加一个Now方法，所以Borglet可以删除了（只有OOMCandidate调用Now方法）Borglet到调用委托为了调用TimerKeeper。

让Task提供Now方法，是解耦的一步。最终，使用Task的地方应该切换到TimerKeeper，但是这需要逐步切换。

还需要继续持续重构Borglet的结构。

以上描述，第一行描述了提交做了什么并且是如何做到。其他的描述了实现，提交变更的背景，和方案解决不了的，以及未来的方向。这也解释了为什么要做这个变化。

小的提交需要上下文

给status.py添加python3构建规则

这允许已经用python3的使用者一来这个规则构建系统。这鼓励新的使用者使用Python3，而不是Python2，而且搞定了一些自动构建脚本。

以上第一句话描述做了什么，其他的描述为什么要这么做，以及一些背景信息。

提交检视之前，重新看一下描述

提交在检视过程中可能会产生很大变化。在提交之前在看一下注释，确保注释还可以很好的描述提交做了什么。

小的提交

为什么写小的提交？

小的提交有以下特点：

• **检视更快。**相比需要30分钟检视一大笔提交，花费多个5分钟快速检视一笔要简单的多。
• **检视更彻底。**如果是一比很大的提交，可能会很沮丧，前前后后翻阅代码，这样重要的点有可能遗漏掉了。
• **更容易发现BUG。**代码更少，BUG更容易发现。
• 如果被拒绝了，浪费的工作量更少。
• 更容易merge。提交太大，merge的冲突越多。
• **更容易设计的更好。**代码更少，更容易打磨的更好。
• **更不容易因为检视阻塞。**发送编码的一部分，可以在检视过程中继续向下编码。
• 更容易回退。

注意检视者是可以单方面拒绝提交的。最好是用一系列小提交代替一大笔提交。在完成后再拆分或者说服检视者合入一大笔提交，都是很费时间。更简单的是直接用更小的提交。

多小是小？

一般来说，正确的大小是一个独立的变化。意思是：

• 提交的变更最小化到只做一件事。一般是特性的一部分，而不是整个特性。通常最好写小一些的提交，而不是大的。和你的检视者共同发现可以接受的大小。
• 所有需要检视者理解提交的参考，应该是在提交中、提交描述、已经存在的代码和已经检视过的代码中。
• 提交合入后，程序还可以正常使用。
• 提交小的不至于很难理解。如果添加了一个新的API，必须同时添加使用说明，用于更好的理解API怎么使用。这也能防止提交了无用的接口。

没有明确的标准说明多大是大。一般来说，100行看起来还好，1000行就显得很大，但是这取决于检视人员。文件数量也可能影响大小，200行的提交在一个文件里还好，但是分割到50个文件看起来就很大了。

请记得，尽管你开始编码的时候已经非常熟悉了，但是检视者可能不知道上下文。对你来说可能正好是可接受的大小，可能会压倒检视者。如果有疑问，要比你能想到的提交更小一些。检视者通常不会嫌提交太小。

什么时候大提交是好的？

有些情况下大的提交也不差：

• 通常你可以把整个文件的删除视为一行，因为这不需要花很长时间来检视。
• 有时候是因为一些可信任的自动的重构工具自动修改和生成的，检视人只是合入他们。这种提交可以很大，即使要考虑上面的规则。

分割文件

另一种方式分割提交，就是把独立功能的提交分给不同的人检视。

比如你可以把protocol buffer提交和使用的代码提交分为两笔检视。你必须先提交proto，但是可以同时检视。如果这么做，你需要提供给两位检视者修改背景。

还有个例子，把配置和代码分开提交；这也很容易回滚，如果需要的话，提交到生产环境要比修改代码变更来的快。

把重构分开提交

最好把重构和特性、修复问题分开。比如，移动代码或者修改名字，应该和修复BUG在不同提交里。这对检视人员理解提交的变更更有好处。

小的cleanup像临时变量修改名字这种可以包含在特性和修复BUG中。这取决于开发者和检视者的选择，什么样的重构提交混在其他提交里，会导致检视者很难理解。

保持测试代码在同一笔提交里

避免把测试代码分割到不同提交里。测试验证了代码修改，应该包含在同一笔提交里，即使这会增加变更代码量。

然而，独立的测试修改可以分开提交，如重构的提交。包含：

• 验证已存在的代码，提交新的测试。
• 重构测试代码
• 重构大的测试框架

不要让构建失败

如果你有好几笔要提交，确保每笔提交合入后，系统运行都是正常的。否则你有可能在两次提交之间引起开发人员的环境中断。

没办法做的足够小了

有时候你会遇到一些情况就是你的提交看起来有些大。这确实是真的。编写小的提交的开发人员，总会找到办法把实现变成一系列小提交。

在编写大提交之前，确保已经有一系列纯粹的重构为这个提交铺平了道路。和同事交谈，看看有没有人对如何用一系列小提交实现功能有什么想法。

如果这些方法都失败了，征得你的检视认的同意准备好检视一笔大的提交，这样他们就可以提前有所准备。这种情况下，准备好检视过程会很长，警惕会带来的BUG，以及多做一些测试。

如何处理检视意见

以下是一些有帮助的意见，可以帮助你处理检视者的意见。

不要自己去做

检视的目标是维持代码库和产品的高质量。当一个检视人员提供了一些致命的问题，考虑他们是为了帮助你、代码和Google公司，而不是对你的个人能力的攻击。

有时候检视者在意见里表现出了不满和沮丧。这对检视人员来说不是好的实践，但是作为开发者，你应该对此有所准备。问问自己，检视者试图告诉我什么样的建设性意见？然后按照他们实际想表达的去做就行了。

**永远不要对检视意见发火。**这严重违反职业礼仪，并且会一直存在在检视工具的记录中。如果你实在太生气而无法礼貌的回答，那就离开电脑一会，或者去做些其他事情，直到你能冷静下来去礼貌回复。

通常情况下，如果检视人员没有用建设性或者礼貌的方式反馈给你意见，可以亲自和他解释。如果你无法亲自解释或者在一个视频会议上，那就发送一个私密的邮件。礼貌的告诉你不喜欢什么喜欢什么。如果他们任然在这种私密的讨论中无法用建设性的方式反馈，或者没有意向这么做，那么适当的升级到你的管理者那里。

修复代码

如果一个检视者说看不懂代码，那第一件事应该是自己先把代码写的更清晰一些。如果代码没法更清晰了，那就加一些注释说明代码为什么在这。如果注释也无法说明，再在检视工具里解释。

如果你的部分代码检视人看不懂，说不定未来的开发者也看不懂。在检视工具里回复不会帮助到未来的代码阅读者，但是如果把代码写的更清晰或者添加注释，才可以帮助到他们。

为自己思考

搞一笔提交需要很多工作。完成一笔提交通常很满意，就感觉这似乎完成了任务，而且非常确定不再需要额外工作了。所以当检视人员反馈意见回来发现还可以改善的时候，很容易想到是意见错了，检视人在搞不必要的阻塞，他们应当直接合入提交。然而，不管你怎么想这一点，花点时间想想检视者是为了代码库和Google给了有价值的意见。你的第一个问题应该是“检视者是对的吗？”

如果你无法问出这问题，那么看起来检视者应该把意见搞的更清晰。

如果你考虑过这个，任然觉得你是对的，那就给一个解释，为什么你的做法对代码库、用户、或者Google有益。经常来说，检视人给出意见，希望你能自己思考怎么样更好。你或许比检视人知道的多一点。所以要把他们加入进来，给检视人更多的参考。通常你可以和检视者基于技术事实达成一致。

解决冲突

第一步永远应该是和你的检视人达成一致。如果无法达成一致，参考“检视标准”，那里面给出了这种情况下的原则。