谷歌开源的代码评审规范,值得借鉴!

简介: 谷歌以前建立了一套通用的工程实战指南,它差不多囊括了所有编程语言与各种类型的项目。今天,谷歌将这一套代码评审(Code Review)规范开源了出来,它代表了谷歌最佳实战经验的集合。

项目地址:https://github.com/google/eng-practices

image.png

开源项目作者或其它开发者都能从这个项目获得有用的知识,因此谷歌开源了这一份代码规范,并将持续维护。如项目所言,目前这份代码评审规范主要包含两组独立的文档:


1. 代码评审者的指南


代码评审标准


代码评审希望达到什么


在代码评审中导航修改列表


代码评审的速度


如何写审查的评论


处理代码评审的回退


2.CL 作者指南


写一个好的修改列表描述


构建一些小的修改列表


如何处理代码评审者的评论


其中代码评审者指南包括一些做代码评审的最佳方式,它们都是根据长期经验得出来的。代码评审者指南本来是一个完整的文档,但作者将其分为了 6 部分,读者可根据需要阅读。修改列表(Change List/CL)制定者指南包括一些浏览代码评审的最佳方式,开发者可以快速处理评审结果。

image.png

代码评审都在干些什么


代码评审最主要的目的是确保代码库一直保持「健康」的状态,代码评审的所有工具和过程都是为了这个目的而构建的。代码评审会系统化地查一遍源代码,并希望检查出开发初期未察觉的一些错误,从而提升代码质量。


那么代码评审都在感谢什么呢?一般而言,代码评审希望完成以下的评估:


设计:代码是不是经过精心的设计,并适合我们的系统?


功能性:代码的行为是否和作者的意图保持一致?代码的行为方式对用户是否正常?


复杂度:代码能更简单一些吗?在未来,其它开发者能更容易地理解并使用这些代码吗?


测试:代码是不是正确的,是不是通过了精心设计的自动测试?


命名:开发者是不是选择易于理解的名称给变量、类和方法进行命名?


评论:代码评论是不是足够清晰并有用?


风格:代码是不是采用了标准的编写风格?


文档:开发者是不是更新了相关的文档?


既然代码评审要进行众多的检查,那么找一个优秀的评审者就非常重要了。一般对于修改列表的不同部分,都会有不同的评审者进行细致的审查。另外,关注公众号Java技术栈回复手册可以获取阿里巴巴的最新Java开发手册,非常有价值和参考意义。


当然如果是结对编程,且你的队友能进行高质量的代码评审,那么这样写的代码一般可以视为已经过评审了。此外,我们也可以进行面对面的评审,评审者会问开发者一些问题。


代码评审的通用规范


整个代码评审指南分为了很多模块,我们也没办法全部介绍一遍。因此,在本文的最后,我们将介绍谷歌开发者在做代码评审时,最一般的评审标准。

谷歌表示他们以如下规则作为期望的标准:


「通常而言,一旦修改列表能提升整体代码的健康程度,那么即使修改列表不完善,评审者同样也应该倾向于批准该列表。」


这条准则是所有代码评审指南的最高原则。它也会有一些限制,例如,如果 CL 添加了一些评审者不需要的特性,那么即使代码经过了精心的设计,评审者也应该不予通过。


这里的一个关键点是没有「完美」代码这个概念,只有更好的代码。评审者不应该要求代码作者在批准前对每一小块 CL 进行打磨。


相反,评审者应该权衡向前继续开发的需求和修改建议的重要性。评审者要求的是持续性地改进,而不是追求完美的代码。CL 作为一个整体,如果它能提升系统的可维护性、可读性和可理解性,那么就不要因为它还不完美而推迟数天或数周更新。


评审者应该经常留下一些评论,以表达能导致更好性能的做法。如果这些做法并不是非常重要的,那么需要加上前缀「Nit:」,从而令代码作者知道这些内容是可以忽略的。《两年 Code Review 实战经验分享!》这篇推荐看下。


评审指导


代码评审有一个很重要的功能,即教开发者一些开发经验,不论是语言、框架还是一般软件设计准则。留一些评论总会帮助开发者学习一些新的知识,共享知识也是改善系统代码健康状态的重要部分。当然,如果评审者的评论仅仅只是教育性的,且对于标准要求不那么重要,那么还是要加上前缀「Nit:」的。


评审准则


技术事实和数据要优先于观点与个人风格。


在代码风格方面,谷歌的代码风格指南是最权威的参考资料。任何不在风格指南中的代码习惯,都属于个人风格,但我们应该保证基本的风格和谷歌风格指南是一致的。


谷歌风格指南:http://google.github.io/styleguide/


软件设计方面几乎不会有纯粹的风格问题,或者纯粹个人的习惯问题。很多风格问题都基于一些基本准测,它们并不是简单地由个人观点决定的。此外,如果代码作者通过数据或基本工程原则证明了几种方法同样有效,那么评审者应该接受作者的风格。否则,偏好的选择还是取决于软件设计的标准原则。


如果没有其它适用规则,那么评审者可以要求作者的偏好与当前代码库保持一致,同时不对整体的代码健康水平产生影响。


解决冲突


在代码评审中,如果发生了任何冲突,第一步应该是开发者和评审者基于本项目的 CL 指南达成共识。当达成共识非常困难时,开发者与评审者应该面对面地交流,而不只是通过审查中的评论来交流。如果开会讨论还解决不了,那么就要扩大会议了,我们可以通过与代码维护人员、工程经理等开发者的交流,达成最终的共识。


以上只是代码规范的一般标准,它还是非常抽象的,如果读者想要了解更多细节的内容,那么可以继续查看该项目。

目录
相关文章
|
自然语言处理 Java Go
项目总监必看:如何利用Git深度统计团队代码贡献?多语言实践教程揭秘!
项目总监必看:如何利用Git深度统计团队代码贡献?多语言实践教程揭秘!
332 0
OpenHarmony系统文档贡献的写作规范
已经有一段时间的连续写作了,这次我们来谈谈在OpenHarmony上贡献自己的文档的规范,同时也是一种平时写作的可以参考的规范,话不多说,开始了~~
123 0
|
程序员
开发新概念:代码管理(代码框架)
开发新概念:代码管理(代码框架)
152 0
|
供应链 安全 IDE
墨菲安全正式发布 murphysec 开源项目!让开发者更安全的使用开源代码
墨菲安全正式发布 murphysec 开源项目!让开发者更安全的使用开源代码
510 0
墨菲安全正式发布 murphysec 开源项目!让开发者更安全的使用开源代码
|
开发工具 git 开发者
向开源项目贡献代码那点事
向开源项目贡献代码那点事
148 0
|
存储 缓存 文件存储
|
前端开发 Java 测试技术
Google 鼓励的 13 条代码审查标准,建议收藏!
以下为译文: 在本文中,我们将简要介绍13条代码审查标准,希望能够通过这些标准极大地帮助改善软件的质量,同时让开发人员保持心情愉悦。
|
消息中间件 运维 前端开发
做一个优秀的开源项目,需要注意哪些方面?
如果你想发布一个开源库,请确保它有以下特点: 清晰的依赖性和安装说明 至少有一个简要的文档指南 修改日志和仓库中的标签 关于支持的语言、运行时、工具版本的信息和项目的成熟度 一个可以让用户提问和交流的邮件列表 缺少任何一项都会造成一些用户的愤怒和沮丧,当然同时也浪费了时间。
352 0
|
安全 算法 Java
阿里巴巴开源Java编码规范背后的故事
《阿里巴巴Java开发手册》(下称《手册》)凝聚了阿里集团很多同学的知识智慧和经验,这些经验甚至是用血淋淋的故障换来的,希望前车之鉴,后车之师,能够帮助更多的开发者少踩坑,杜绝踩重复的坑。
7942 0
|
自然语言处理 算法 安全
谷歌开源内部代码评审规范
谷歌成立于 1998 年,以搜索起家,到目前为止已经发展了 21 年。在过去的 21 年中,谷歌不断创新,开发了七款产品,拥有超过 10 亿级活跃用户,谷歌的工程师文化一直被认为是优秀且特别的。近日,谷歌开源了其内部一直在使用的代码评审规范,看看谷歌工程师是如何评审代码的。
1242 0