简短化的CL

为什么要写成一系列简短的CL?

简短的CL有这些好处:
  • 代码评审更快 与比起花30分钟评审一个大型的CL相比,对评审者来说花5分钟审查一系列小的CL更加容易.
  • 评审更加彻底。 进行较大的更改后,审阅者和作者往往会因大量详细评论的来回移动而感到沮丧,有时这些评论会漏掉或遗漏重要的观点。
  • 减少导致bug的可能性。 由于您所做的更改较少,因此您和您的审阅者更容易有效地推断出CL的影响,并查看是否导致bug。
  • 减少不必要的工作 当你写了一个巨大的CL,然后评审者觉得你总体方向错了,这会导致你浪费大量的工作。
  • 更方便合并代码 因为大型的CL会导致大量的冲突,因此合并大型的CL会浪费很多时间,并且这将会是你经常做的工作。
  • 有助于你作出更好的设计 优雅的设计并且完善一个小的改动比大的改动更加容易
  • 降低评审者的难度 提审部分改动,不会影响你继续编码。
  • 回滚更容易 大型CL很有可能会在初始CL提交和回滚CL之间更新修改文件,从而使回滚变得复杂(中型CL也可能也需要回滚可能也会这样)。
注意! 评审者可以因为你的改动过于巨大直接拒绝掉你,通常他们会感谢您的贡献,但要求您以某种方式使它成为一系列较小的CL。不管是你把这些改动拆分成小的改动,还是和评审者争论让他接受都会耗费你大量的时间。但是编写小型改动就不会有这样的问题。

怎么样算简短?

通常,一个CL合适的大小是:只包含一个独立的更改。 这意味着:
  • CL所做的最小更改仅解决了一件事情。 通常,这只是功能的一部分,而不是一次完整的功能。 通常,宁可编写过小的CL也不要写太大的CL。你可以和你的评审者商量找到合适的尺度。
  • 审阅者需要了解的有关CL的所有内容(将来的开发除外)都在CL,CL的描述,现有代码库或他们已经查看过的CL中。
  • CL应当包含相关的测试代码(#test_code)
  • CL合进去后,对于用户和开发者而言,系统能继续正常工作。
  • CL不够小的话会导致其难以理解。如果你新增加了api,那么在同一个CL应该包括这个api用到的方法,以便评审者更好的理解。也能防止检入没有用的api。
多大算大,没有一个明确的要求。 一般100行是一个合理的大小,而1000行太大,当然这也取决于您的审阅者的判断。 更改分布的文件数量也会影响其“大小”。 可以在一个文件中进行200行的更改,但是将其分布在50个文件中通常会太大。
请记住,尽管从您开始编写代码起就一直与您紧密联系,但审阅者通常没有上下文。 对您来说,看起来像可接受大小的CL可能会让您的审阅者不知所措。毫无疑问,尽可能把CL些小是正确的。评审者很少抱怨CL太小

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

在某些情况下,较大的更改没有那么糟糕:
  • 通常,您可以将整个文件的删除视为更改的一行,因为它不会花费审阅者很长时间来审阅。
  • 有时,您完全信任的自动重构工具已经生成了一个较大的CL,而审阅者的工作只是检查健全性,然后指出他们认为需要修改的地方。 这些CL可能更大,尽管会有一些风险(例如合并和测试)仍然适用。

按文件分类

拆分CL的另一种方法是通过将文件分组,如果这些文件将是独立的更改,可以分配各不同的审阅者。
比如: 你提交一个修改的CL,创建一个修改的缓冲区,另一个CL的代码修改也可以提交到这里面。你必须按照顺序提交CL,但是审阅者可以同时进行审阅. 如果这么做,你需要尽可能告诉所有审阅者另一个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的实践和方法。
如果所有这些选项都失败了(这种情况很少见),那么请事先获得您的审阅者的同意,告诉他们一个巨大的CL将要来临。 在这种情况下,审查过程会耗费极其长的时间,这样请花费更多的时间去写测试代码,避免引入bug。
Copy link
On this page
为什么要写成一系列简短的CL?
怎么样算简短?
什么时候大型的CL也是可以的?
按文件分类
把代码重构分离出来
将相关的测试代码保存在同一CL中
不要破坏结构
小到不能再小