谷歌最佳实践 - 代码审查指南

来源

代码审核标准

代码审核的核心目的是保证谷歌代码在不断的改进发展过程中还能持续保证健康。所有代码审核的流程与工具都是设计用于确保这个目标。
为了实现这个目标,我们做了很多的权衡。
首先,研发人员必须能够在个人的任务上做出改进。如果你从不提交代码的改进,那产品就无法提升。同样的,如果代码审核者对于任何变更提交都设置很高的门槛,也会影响开发者今后也提交改进的热情。
从另一个方面说,代码审核者的责任是要确保每个变更清单(CL)[1]的内容都能够在全局上保证代码质量,而不会随着时间导致质量不断变差。这样实际上是比较困难的,整体代码的质量削弱实际上是由于代码健康度中很小的问题不断累积引发的,特别当一个小组在明确工期的压力之下,需要走一些捷径才能够达成目标。
审核者对于他们审核的代码是有权利和责任的。他们需要确保代码基线是一致风格,可维护,以及在《代码审核应该审核什么》一文中提到的其他内容。
所以,我们期望代码审核中包含如下标准规则:
通常情况下,审核者需要确认一个变更清单对于整体系统代码一定是有质量提升的,哪怕目前还不是完美的。
在代码审核的指导规则中,这是最重要的原则。
当然,这条规则存在很多的限制。例如变更清单包含了一个系统不允许加入的特性,即使代码的设计和质量很好审核者也可以直接拒绝。
有一个很重要的观念,“完美”的代码是不存在的,只会有更好的代码。审核者不应该要求在接受提交前,就要提交者打磨变更清单中的每个小细节。审核者需要在系统持续改进和建议重要变更之间做出平衡。与其要求完美,审核者更应该重视的是持续改进。当一个变更清单对于整体系统的可维护性,可读性,可理解性都有改进时,就不应该因为“不完美”而被拒绝几天或者几周。
审核者应该一直都能自由的对可以改进的地方留下注释意见,但是如果这并不是很重要,可以在前面加上前缀如“Nit:”这样能让提交者知道这只是他们能够忽略的一个小优化点。
注意:本文档中的不会为任何恶化代码健康的提交做辩解,只有在特定的经济情况下你可以考虑这么做。

导师制

代码审核者有一个很重要的作用就是指导开发者关于语言、框架、或者软件设计的通用规则的一些新知识。能够留下一些评论帮助开发者学习一些新知识总是好事情。分享知识对于代码质量改进也是一件好事情。你需要谨记,如果你的评论是处于纯粹教育的目的,而不是本文档中提到的评判标准,请加上“Nit:”的前缀或者提示提交者这些在变更清单中并非需要强制修改。

原则

  • 专业的现实情况与数据否定意见和个人偏好。
  • 针对样式问题,《样式指南》是绝对权威。任何纯粹的样式观点(如空格等)在样式指南中没有提及的都是个人偏好。这部分的风格也应当统一,如果没有事先约定则接收提交者的样式。
  • 软件设计的方面几乎不可能会是纯粹的样式问题或者个人偏好。 这些都是基于根本性的原则构建的,应当倚重于这些原则,而不是个人意见。有时会存在一些有限的选项。如果提交者能够证明(通过数据或者基于实际的工程原则)这些做法都是相近的,审核者应当接受提交者的偏好。否则就要取决于软件设计的标准规则。
  • 如果没有其他可应用的规则,审核者应当要求提交者与现有的代码基线保持一致,只要变更内容不会影响到系统的健康程度。

解决冲突

面对代码审核中的任何冲突,第一步永远应该是开发者和审核者达成一致,原则就是基于本文档和其他的文档如《变更提交者指南》和《审核者指南》。
当很难达成一致时,提交者和审核者面对面的沟通或者语音沟通就很有必要,而不是通过代码审核的评论来解决冲突。(但是记住可以将讨论的结果以评论的形式记录在变更提交中,以便将来方便查阅)
如果上面的方法还是不能解决冲突,常见的方法就是升级问题。升级的方法通常是发起团队会议,要求技术领导参与其中,征询代码维护者或者管理者的意见,最终做出决策。不要因为提交者和审核者无法达成一致而闲置一份提交。

下一篇预告:代码审核时,我们应当寻找什么内容。

总结:
谷歌的代码审核中,首先要建立的是原则,编码样式、软件设计等等的原则。基于这些原则才能判定系统代码的健康程度,不是以个人喜好或者使用了某种框架。
审核者有拒绝提交的权利,但是背负着系统改进提升和维持健康程度的责任。要熟悉企业的各种原则产生自己的判断,并且将自己的意见分为必须建议两种等级。
面对冲突时,不应当是提交者或者审核者某一方面的责任,而是双方应当据理力争尝试说服对方,当相互无法说服时可以升级问题,请求上级或者外部来评判。
在这些里面,所有的角色都有一个很重要的原则:真正的尊重代码,热爱代码。而不是随便糊弄任务,随便提交,随便审核,随便通过并且合并。这个要靠团队的文化和企业的健康来支撑。


  1. CL: 是 "changelist" 的缩写,指提交到版本控制或者提交给代码审核的一个完整自包含的变更。 在其他组织中(非股改革)称之为变更(change)或者补丁(patch)。

©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 203,324评论 5 476
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 85,303评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 150,192评论 0 337
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,555评论 1 273
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,569评论 5 365
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,566评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,927评论 3 395
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,583评论 0 257
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,827评论 1 297
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,590评论 2 320
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,669评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,365评论 4 318
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,941评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,928评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,159评论 1 259
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 42,880评论 2 349
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,399评论 2 342

推荐阅读更多精彩内容