View on GitHub

eng-practices-cn

谷歌工程实践

简短化的CL

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

简短的CL有这些好处:

注意! 审查者可以因为你的改动过于巨大直接拒绝掉你通常,他们会感谢您的贡献,但要求您以某种方式使它成为一系列较小的更改。不管是你把这些改动拆分成小的改动,还是和审查者争论让他接受都会耗费你大量的时间。但是编写小型改动就不会有这样的问题。

怎么样算简短?

通常,CL的正确大小是一个独立的更改。 这意味着:

多大算大,没有一个明确的要求。 对于CL而言,100行通常是一个合理的大小,而1000行通常太大,但这取决于您的审阅者的判断。 更改分布的文件数量也会影响其“大小”。 可以在一个文件中进行200行的更改,但是将其分布在50个文件中通常会太大。

请记住,尽管从您开始编写代码起就一直与您紧密联系,但审阅者通常没有上下文。 对您来说,看起来像可接受大小的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。

下一节: 怎么处理审阅者的评论