四步做好 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 平台进行。良好的工具可以帮助更好的进行代码审核

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