写点什么

四步做好 Code Review

  • 2021 年 12 月 01 日
  • 本文字数:5194 字

    阅读完需:约 17 分钟

四步做好Code Review

本节课为《如何做好 Code Review》,内容包括:为什么要做好 Code Review、如何做好 Code Review、例子:Python 代码的 Code Review、如何成为一个好的 reviewer 和公司针对 Code Review 的措施五个方面。


为什么要做好 Code Review


Code Review 是提升代码质量的最好方法

强化 Code Review 是提升代码质量的第一选择。


在代码开发过程中,我们越早发现问题、定位问题,在修复问题时付出的成本越小。


大约有 50%以上的 bug,都是在做 Code Review 时发现的。前期做好 Code Review,后期将会减少反复修改等不必要的复工。


Code Review 能够在团队内传递知识

从知识传递的角度看,Code Review 是极为重要的。


做好 Code Review,能够帮助团队传递知识、沟通交流、互相学习,能够提升学习能力、提升编写代码能力、提升代码质量、提升工作效率、降低项目风险。


另外,基于 codebase 可以使我们了解项目全局,培养系统的思考方式。


Code Review 是辅导怎么写代码的最好方法

我们要意识到,做 Code Review 可以学习到别人的经验,同时也可以向别人传递我们的经验。


如果我们想辅导别人,最好的办法就是让对方先写一段代码,我们对他的代码进行 Code Review。在辅导他人的过程中,我们可以快速地发现问题,从而帮助改进。


做好 Code Review

可以增加公司对最顶级开发者的吸引力

工作中是否有 Code Review 对于公司或团队来说非常重要。不但对于公司或团队内的人员有所提升,而且能够吸引出色的开发者加入开发团队。


未做好 Code Review 的公司或团队有如下特点:

①代码质量差。

②团队内人员备份差。

③其人得不到有效的辅导,提高慢。


为什要提高代码质量?

①提高代码质量可以提高代码的可读性。

②提高代码质量可以提高代码的复用性和参考性。

③提高代码质量可以减少 bug 出现的风险。

④提高代码质量可以减少后期补丁的风险。

⑤提高代码质量可以降低代码失控的风险。

⑥提高代码质量可以降低项目重构和升级的麻烦。


为什么要提高写代码的能力

①代码能力如果停滞不前,对于个人而言,将导致职业危机。

②代码能力如果停滞不前,对于团队而言,将意味着团队没有成长。


Code Review 是一个非常重要的提升代码质量和代码能力的手段。无论是从个人发展角度,还是团队发展角度,我们都需要重视 Code Review。


如何做好 Code Review


在 Code Review 中可能发现的问题

→ 拼写错误;

→ 未优化的代码;

→ 不必要的复杂代码;

→ 已经实现过的代码,又重复实现;

→ 注释不全;

→ case 没有覆盖全等等问题。


在 Code Review 中要有一个好的态度

要做到以下几点

(1)对所有检查的代码逻辑要做到“完全看懂”,对于审核的代码,熟悉程度要做到“如数家珍”。如果在审核代码后,对代码的逻辑和背后的原因仍然很模糊,则是一个失败的 Code Review。


(2)好代码的标准,不仅仅是“可以运行通过”,在正确性、可读性、可重用性、可运维性等方面上,都需要综合考虑。


(3)建立 Code Review 和写代码一样重要的意识。即:

①Code Review 和写代码一样,也有产出,即产出更高质量的代码。

② 审核代码在很多情况下比写代码还要辛苦,需要理解和找出问题等。


(4)以提升代码质量为最终目标。


(5)要投入足够的时间和精力。

①审核代码花费的时间经常和写代码一样多,有时甚至比写代码的时间更多,要有时间意识。

②要有责任意识。如果出现 bug,不仅仅是写代码人员的职责,也不仅仅是 QA 的职责,代码审核者也需要承担相当大的责任。


在 Code Review 之前,一流代码的特性


一流代码有以下特性:①高效性;②鲁棒性;③简洁;④简短;⑤可共享;⑥可测试;⑦可移植;⑧可监控;⑨可运维;⑩可扩展。


将以上十条标准进行总结精简,可归纳为:

①代码的正确和性能;

②代码的可读和可维护性;

③代码的可运维和可运行;

④代码的可共享和可重用;

在 Code Review 时,综合考虑以上一流代码的特性,可以快速提升代码质量、提升编写代码的能力等。


在 Code Review 时

需要有对 bad code 进行简单判断的能力

除了要了解一流代码的特性之外,在 Code Review 时,需要有对 bad code 进行简单判断的能力。通常 bad code 有以下特点:


①5 分钟内不能看懂的代码。

不能快速看懂的代码,一定是有问题的代码,可以先抛回给编写代码人员进行修正。一般一个函数的操作不能超过 6 个 step,如果超过这个数量,则需要重新调整编码逻辑。


②需要思考才能看懂的代码。

好的代码阅读时基本不用动脑子,甚至看注释就能看懂。


③需要来回翻屏才能看懂的代码。

好的代码,经常在一屏内就是一个完整的逻辑。


④没有空行或注释的代码。


在 Code Review 时,发现不会用段落、不会写注释的代码,肯定不是好的程序员写的代码,可以直接打回给编写代码人员进行修正。


Code Review 的注意事项

①在必要时,review 的双方做面对面的沟通。

面对面沟通并不是单指当面沟通,还包括云共享、电话、视频沟通等。在沟通时,对于背景、关键点等应进行说明,便于 reviewer 的理解。在必要时,应提供设计文档。


②对于关键模块,应该建立 owner 制度。

所有提交的代码,必须由 owner 做最终确认。由 owner 掌握全局,并建立明确的责任关系。


③检查中发现的问题,要一追到底。


④要注意细节。对每一行提交的代码,都要进行检查。


⑤Code Review 的方式,要小步快跑。每次提交 review 的代码量不要太多,降低复杂度。在特殊情况时,比如一个新模块的构建,最好逐步完成,通过多次进行提交。


⑥要为 Code Review 预留出足够的时间。Code Review VS Coding 的时间,有时可能达到 1:1。在这里需要考虑到有时会做大的修改,科学地规划工作量,尽量避免出现时间倒排。


⑦注意每天 review 代码的数量不宜过多。


Code Review 的步骤


Code Review 的步骤为以下几点:

Step1:先看系统全貌

不深究细节,浏览系统全貌,理清模块划分的逻辑、模块间的关系、如何构成的整个系统等。


Step2:进入模块级别

同样不深究细节,浏览模块内的全貌,判断模块切分是否合理,理清模块内的逻辑,明确关键数据、关键的类和函数等。


Step3:理清类、函数内部的逻辑。


Step4:进入细节。

比如 Layout、命名等。


人为因素

除了代码上的问题,在 Code Review 过程中还会有一些人为因素,例如:

①QA 人员

好的 QA 人员不仅仅会发现系统中的 bug,还会质疑或提出产品需求,挑战或优化系统架构和实现方式。


②Code Reviewer

好的代码审核人员不仅仅指出代码表面的问题,还会检查系统需求分析的质量、接口或函数定义的合理性、模块划分的合理性、系统关键机制的合理性等。


例子:Python 代码的

Code Review


以 Python 为例,从 Python 的编码规范和 Python 编程规范的部分说明两个维度来看一下 Code Review 的细节。这些 Code Review 细节,在其他语言中基本都是相通的。


Python 的编码规范

(1)代码要写的漂亮。

(2)代码要明确直接,不要含蓄表达。

(3)代码要简洁,一个函数可以实现的功能就不要写两个函数。

(4)代码深奥胜过代码复杂。代码可以写的深奥难懂,但是不能写的过于复杂。

(5)代码要平铺直叙,不要层层嵌套。

(6)代码要做到合理间隔。

(7)代码可读性非常重要。

(8)代码要有普适性。尽量规避代码特殊性,用最简洁最通用的代码来实现。

(9)代码要实用。

(10)要重视所有发现的错误。

(11)代码逻辑要清晰。在含糊混乱的面前,我们要拒绝猜测。读写代码时,不要出现“好像”、“可能”、“似乎”等猜测。当一段代码很难懂的时候,代码一定存在问题。

(12)写代码要注重行动。

(13)代码实现方法要简洁。如果一个方法很难解释,就意味着这个方法存在一定的问题。

(14)要重视命名空间的使用。


关于 Python 编程规范的部分说明

Python 编程规范有九个维度。


(1)模块的划分

我们要对模块有概念,这是整个系统的基础。

①一个.py 文件是一个模块。

②模块的划分对软件的长期维护非常重要。

③每个模块都应该有特定的功能。

比如:配置文件的读取,网页文件的写入,网页文件的解析,一个内存数据表,一个抓取的线程等等。

④多个本应独立的模块,写到一个.py 文件中是常见的错误。从 Code Review 角度看,首先就是要看模块切分的对不对。


( 2 )数据的封装

在 Code Review 时,要着重注意数据是否封装这一问题。


( 3 )import

Import 在使用过程中,禁止使用 from xxx import yyy 语法直接导入类或函数。禁止使用 from xxx import *这样的方法。这样做的目标是:容易判断代码中使用外部变量或函数的来源。


如果使用禁止中的语法,会大大增加判断来源的难度,以及代码阅读的难度。


在 Code Review 时,遇到这种情况,及时将代码打回给编程人员进行修正。


( 4 )异常

对于异常的处理有以下几点需要注意:

①异常的使用

使用异常前请需要详细了解异常的行为。不要主动抛出异常,使用返回值。如果一定要抛异常,需要注释进行说明。


②异常的获取强制

除非重新抛出异常,否则禁止使用 except:捕获所有异常,不建议捕获 Exception 或 StandardError。


在实际编码中建议 try 中的代码尽可能少,避免 catch 住未预期的异常,掩藏掉真正的错误。底线是至少要打印异常的日志,而不是捕获后直接 pass 通过。


在对异常进行处理时尽量针对特定操作的特定异常来捕获。


常犯的错误是:一是对 IO 等操作不捕获异常。二是捕获异常区域很大。


③函数的返回值

如果函数会抛出异常,需要在函数的注释中明确说明。


在 Code Review 时,需要注意上述问题,及时返回给编程人员进行修正。


( 5 )构造函数

对于构造函数有以下几点需要注意:


①规范:

类构造函数应该尽量简单,不能包含可能失败或过于复杂的操作。


②解读:

在构造函数中常出现的错误是:无法判断、或捕获异常。


( 6 )函数返回值

对于函数返回值有以下几点需要注意:


①规范:

函数返回值必须小于等于 3 个。返回值超过 3 个时必须通过 class/namedtuple/dict 等具名形式进行包装。


②解读:

a. 多数情况下的错误,是因为很多人不会思考和设计函数的语义。


函数描述涉及的三要素为:功能描述、传入参数描述和返回值描述。


每个函数都应该有足够明确的语义。基于函数的语义,函数的返回值有三种类型:


第一种类型:在“逻辑判断型”函数中,返回布尔类型的值——True 或 False,表示“真”或“假”。


第二种类型:在“操作型”函数中,作为一个动作,返回成功或失败的结果——OK 或 ERROR。


第三种类型:在“获取数据型”函数中,返回一个“数据”,或者返回“无数据/获取数据失败”。


b .另外,函数需要有返回值,对于正确或错误的情况,在返回值中要有体现。


c .还有一个问题是:Python 的数据格式不需要定义,过于灵活。当程序规模变大、维护周期变长时,会导致后期极难维护。


应对措施是:多写注释,写清楚返回值说明、参数说明。


在 Code Review 时,注释未写清楚的代码,一定要打回给编程人员,进行修正、补注释。


( 7 )代码长度

关于代码长度有以下几点需要注意:

①每行不得超过 120 个字符。避免在终端上显示出现折行。


②函数长度不得超过 100 行。函数过长会增加理解函数逻辑的难度。Python 的函数应尽量控制在 30~40 行之间。


在 Code Review 时,代码过长,建议全部打回给编程人员进行修正。


( 8 )空行、空格

关于空行、空格有以下几点需要注意:

①空行

文件及定义之间隔两个空行。比如类或全局函数。类方法之间隔一个空行。


②空格

逗号、分号、冒号前不加空格,后边加一个空格。所有二元运算符前后各加一个空格。


在 Code Review 时,需要着重注意空行和空格。空行和空格不是可有可无的。空行和空格的存在,是为了增加可读性。不好读的代码,一律打回给编程人员进行修正。


( 9 )注释

关于注释有以下几点需要注意:

Python 中的注释有一个特殊之处是 docstring,docstring 要和“#”注意区分开。


相关规范有:

①使用 docstring 描述 module、 function 、class 和 method 接口时,docstring 必须用三个双引号括起来。


②对外接口部分必须用 docstring 描述。内部接口视情况自行决定是否写 docstring。


③接口的 docstring 描述至少包括功能简介、参数、返回值。如果可能抛出异常,必须使用注释进行说明。


④每个文件都必须有文件声明,文件声明必须包括以下信息:版权声明、功能和用途简介、修改人及联系方式。


在 Code Review 时,不符合上述规范的,及时打回给编程人员进行修正。


如何成为一个好的 reviewer


代码审核的质量,和审核者的代码能力直接相关。代码审核的质量差,反映的是审核者的代码水平。如果作为一个代码审核员不会写代码,就要承认真相,并且要不断提高自己的代码能力。


在这里推荐一些学习资料帮助大家进行学习。

①关于代码的书籍:《编写可读代码的艺术》,《代码整洁之道》。


②综合的书籍:《代码大全》,《201  principles of software development》。


③其他:《代码的艺术》课程,Python Good Coder 考试指南。


公司针对 Code Review 的措施


1、建立高效可运营的代码审核机制,提升代码质量,降低代码评审成本。

①基于平台:icode+bugbye

②代码检查规则分级,分为 ERROR、WARNING、ADVICE 三类,对 ERROR 级别阻塞提交。

③通过统计数据驱动代码检测规则的优化。


2、通过工程能力地图考察项目的 Code Review 情况。


3、所有的 Code Review 行为,都基于 icode 平台进行。良好的工具可以帮助更好的进行代码审核

点击进入获得更多技术信息~~

发布于: 1 小时前阅读数: 6
用户头像

关注百度开发者中心,收获一手技术干货。 2018.11.12 加入

汇聚百度所有对外开放技术、平台和服务资源,提供全方位支持,助力开发者加速成功,实现开发者、消费者和百度三方共赢。https://developer.baidu.com/

评论

发布
暂无评论
四步做好Code Review