[转]四步做好 Code Review

本文转自：四步做好 Code Review - 掘金 (juejin.cn)

 

本节课为《如何做好 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 平台进行。良好的工具可以帮助更好的进行代码审核

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

作者：百度_开发者中心
链接：https://juejin.cn/post/7036655555003285540
来源：稀土掘金
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。