为什么要写简短的CL?

简短的CL有如下好处:

  • 代码评审更快：与花30分钟审查一个很大的CL相比，对审查者来说多次花5分钟审查一系列小的CL更加容易.
  • 审查更加彻底： 进行较大的更改后，审阅者和作者往往会因大量详细评论的来回移动而感到沮丧，有时这些评论会漏掉或遗漏重要的观点。
  • 引入BUG可能性较小： 由于您所做的更改较少，因此您和您的审阅者更容易有效地推断出CL的影响，并查看是否会引入新的bug。
  • 如果审核不通过，减少浪费的工作量： 当你写了一个巨大的CL，然后审查者觉得你总体方向错了，这会导致你浪费大量的工作。
  • 易于合并代码：因为大型的CL会导致大量的代码冲突，因此合并大型的CL会浪费很多时间。
  • 易于设计：小变更的设计带来的代码健康度要比大变更容易完善。
  • 降低审查者的难度：提交部分改动，不会影响你继续编码。
  • 代码回滚更容易：大的CL很有可能会在初始CL和回滚CL之间修改文件，从而使回滚变得复杂。

请注意，审阅者可以单方面拒绝您的更改，这是其酌情决定权。通常，他们会感谢您的贡献，但要求您以某种方式使它成为一系列较小的更改。

怎么才算简短?

通常，一个CL合适的大小是：只包含一个独立的更改。 这意味着：

  • CL所做的最小更改仅解决了一件事情。 一般，这只是功能的一部分，而不是一次完整的功能。宁可编写小的CL也不要写太大的CL。你可以和你的审查者商量找到合适的大小范围。
  • CL应当包含相关的测试代码
  • 审阅者需要了解的有关CL的所有内容（将来的开发除外）都在CL。
  • CL合并后，对于用户和开发者而言，系统能继续正常运行。
  • CL不能太小，否则会导致其难以理解。如果你新增加了api，那么在同一个CL应该包括这个api用到的方法，以便审查者更好的理解。也能防止合并没有用的api。

对于多大，没有一个明确的要求。 一般100行是比较合理的，而1000行就太大了，当然这也取决于您的审阅者的判断。 更改分布的文件数量也会影响其“大小”。 可以在一个文件中进行200行的更改，但是如果修改了50个文件，加起来是200行，那么是一个不太合理的大小。

什么时候大的CL也是可以的?

在某些情况下，比较大的更改没有那么糟糕:

  • 通常，您可以将整个文件的删除视为更改的一行，因为它不会花费审阅者很长时间来审阅。

  • 有时，您完全信任的自动重构工具已经生成了一个较大的CL，而审阅者的工作只是检查健全性，然后指出他们认为需要修改的地方。 这些CL可能更大，尽管会有一些风险（例如合并和测试）仍然适用。

    把代码重构分离出来

    通常重构最好不要和功能修改或者bug fix一起提CL。比如移动或者重命名一个Class，最好和这个Class的bug fix分开提CL。这样对于审阅者来说，理解每个CL单独引入的更改要容易得多。
    不过一些小的代码清理工作比如变量重命名可以包含在功能修改或者bug fix的CL种。 这取决于开发者和审阅者的判断，当然如果巨大的重构包含在同一个CL中会大大增加审阅的难度。

    将相关的测试代码保存在同一CL中

    避免将测试代码拆分为单独的CL。 验证代码修改的测试应该在同一个CL中，即使这样做会增加代码行数。

  • 确保测试涵盖了重要的逻辑。

  • 重构测试代码（例如，引入辅助函数）。
  • 引入更大的测试框架代码（例如集成测试）。

    不要破坏结构

    如果您有多个相互依赖的CL，则需要找到一种方法来确保在提交每个CL之后整个系统都能正常工作。 否则，可能破坏代码结构导致后面的开发者浪费大量的时间等你的提交（如果这些CL提交出了问题，则更长的时间）。

    小到不能再小

    有时候，您会遇到CL很大的情况。 这很少是真的。 练习编写小型CL的作者几乎总是可以找到一种将功能分解为一系列小的更改的方法。
    在写大型CL之前，思考下是不是能够将重构分离出来，这是一个更加清晰的思路。多和你的队友交流学习下他们对缩小CL的实践和方法。
    如果所有这些选项都失败了（这种情况很少见），那么请事先获得您的审阅者的同意，告诉他们一个巨大的CL将要来临。 在这种情况下，审查过程会耗费极其长的实践，这样请花费更多的时间去写测试代码，避免引入bug。
    下一节: 怎么处理审阅者的评论