CodeReview代码审查指南.md

作者：李旭光
引用请标明出处

1．关于Code Review

1.1 Code Review的目的

Code Review是一种用来确认方案设计和代码实现的质量保证机制，通过这个机制我们可以对代码、测试过程和注释进行检查。

Code Review主要用来在软件工程过程中改进代码质量，通过Code Review可以达到如下目的目的：

1. 在项目早期就能够发现代码中的BUG
2. 帮助初级开发人员学习高级开发人员的经验，达到知识共享
3. 避免开发人员犯一些很常见，很普通的错误
4. 保证项目组人员的良好沟通
5. 项目或产品的代码更容易维护

1.2 Code Review的前提

进入Code Review需要检查的条件如下：

1. Code Review人员是否理解了Code Review的概念和Code Review将做什么
   如果做Code Review的人员不能理解Code Review对项目成败和代码质量的重要程度，他们的做法可能就会是应付了事。
2. 代码是否已经正确的build，build的目的使得代码已经不存在基本语法错误
   我们总不希望高级开发人员或是主管将时间浪费在检查连编译都通不过的代码上吧。
3. 代码执行时功能是否正确
   Code Review人员也不负责检查代码的功能是否正确，也就是说，需要复查的代码必须由开发人员或质量人员负责该代码的功能的正确性。
4. Review人员是否理解了代码
   做复查的人员需要对该代码有一个基本的了解，其功能是什么，是拿一方面的代码，涉及到数据库或是通讯，这样才能采取针对性的检查
5. 开发人员是否对代码做了单元测试
   这一点也是为了保证Code Review前一些语法和功能问题已经得到解决，Code Review人员可以将精力集中在代码的质量上。

1.3 Code Review需要做什么

Code Review主要检查代码中是否存在以下方面问题：

• 代码的一致性
• 编码风格
• 代码的安全问题
• 代码冗余
• 是否正确设计以满足需求（性能、功能）
• 等等

1.3.1 完整性检查（Completeness）

• 代码是否完全实现了设计文档中提出的功能需求
• 代码是否已按照设计文档进行了集成和Debug
• 代码是否已创建了需要的数据库，包括正确的初始化数据
• 代码中是否存在任何没有定义或没有引用到的变量、常数或数据类型

1.3.2 一致性检查（Consistency）

• 代码的逻辑是否符合设计文档
• 代码中使用的格式、符号、结构等风格是否保持一致

1.3.3 正确性检查（Correctness）

• 代码是否符合制定的标准
• 所有的变量都被正确定义和使用
• 所有的注释都是准确的
• 所有的程序调用都使用了正确的参数个数

1.3.4 可修改性检查（Modifiability）

• 代码涉及到的常量是否易于修改(如使用配置、定义为类常量、使用专门的常量类等)
• 代码中是否包含了交叉说明或数据字典，以描述程序是如何对变量和常量进行访问的
• 代码是否只有一个出口和一个入口（严重的异常处理除外）

1.3.5 可预测性检查（Predictability）

• 代码所用的开发语言是否具有定义良好的语法和语义
• 是否代码避免了依赖于开发语言缺省提供的功能
• 代码是否无意中陷入了死循环
• 代码是否是否避免了无穷递归

1.3.6 健壮性检查（Robustness）

• 代码是否采取措施避免运行时错误
  • 数组边界溢出
  • 被零除
  • 值越界
  • 堆栈溢出
  • …

1.3.7 结构性检查（Structuredness）

• 程序的每个功能是否都作为一个可辩识的代码块存在
  循环是否只有一个入口

1.3.8 可追溯性检查（Traceability）

• 代码是否对每个程序进行了唯一标识
• 是否有一个交叉引用的框架可以用来在代码和开发文档之间相互对应
• 代码是否包括一个修订历史记录，记录中对 代码的修改和原因都有记录
• 是否所有的安全功能都有标识

1.3.9 可理解性检查（Understandability）

• 注释是否足够清晰的描述每个子程序
• 是否使用到不明确或不必要的复杂代码，它们是否被清楚的注释
• 使用一些统一的格式化技巧（如缩进、空白等）用来增强代码的清晰度
• 是否在定义命名规则时采用了便于记忆，反映类型等方法
• 每个变量都定义了合法的取值范围
• 代码中的算法是否符合开发文档中描述的数学模型

1.3.10 可验证性检查(Verifiability)

代码中的实现技术是否便于测试

1.4 Code Review的步骤

这些是我在平时工作中的经验总结，目前也是按照这个步骤在做。

1. 代码编写者和代码审核者坐在一起，由代码编写者按照UC依次讲解自己负责的代码和相关逻辑，从Web层->DAO层；
2. 代码审核者在此过程中可以随时提出自己的疑问，同时积极发现隐藏的bug；对这些bug记录在案。
3. 代码讲解完毕后，代码审核者给自己安排几个小时再对代码审核一遍。
   代码需要一行一行静下心看。同时代码又要全面的看，以确保代码整体上设计优良。
4. 代码审核者根据审核的结果编写“代码审核报告”，“审核报告”中记录发现的问题及修改建议，然后把“审核报告”发送给相关人员。
5. 代码编写者根据“代码审核报告”给出的修改意见，修改好代码，有不清楚的地方可积极向代码审核者提出。
6. 代码编写者 bug fix完毕之后给出反馈。
7. 代码审核者把Code Review中发现的有价值的问题更新到”代码审核规范”的文档中，对于特别值得提醒的问题可群发email给所有技术人员。

提示
Code Review必备的文档：

• “代码审核规范”文档：记录代码应该遵循的标准。

  代码审核者根据这些标准来Code Review代码，同时在Code Review过程中不断完善该文档。

2．Code Reivew的执行

一个标准的Code Reivew活动应该分为三个阶段：

2.1．事前准备阶段

在一次CR前，对以下内容进行充分准备。

2.1.1．CR的对象

在准备CR代码对象时，我们要注意代码的数量，如果代码量比较大，要对代码进行必要的分解，确定其中的关键代码，对关键代码进行CR，可以达到举一反三的目的。

2.1.2．CR的内容

我们对代码的审查内容很多，如代码的编写是否规范（注释的书写格式、命名规范等）、技术处理规范（异常处理、日志处理、代码组织结构等）、业务实现等。我们不能希望通过一次CR活动，完成所有这些内容的审查，因此我们必须设定本次CR活动内容界限，确定审查重点；

2.1.3．评审规范和标准

在CR前设计确定评审规范和标准是必要，通过规范和标准我们在审查过程中可以有据可依，有理可循，而且还可以做到标准统一。

2.1.4．选择CR活动的参与者

在CR开始前，必须把本次CR活动的对象、审查内容以及审查的规范和标准通报给所有的参与者。

2.1.5．选择CR活动的实施方式。

CR活动有很多形式可供我们选择，我们可以根据实际情况选择桌面式CR、演示讲解式CR、一对一的座位CR等等。

2.2．实施阶段

充分的事前准备，只是做好CR活动的前提，在CR实施过程中，我们要做好以下工作。

2.2.1．准确记录

对于CR过程发现的问题，我们必须清晰准确的记录，可以使用问题点记录单，明确记录的项目和内容。

2.2.2．讲解与提问

CR过程中，要采用代码作者讲解和审查者提问方式。审查者不能只在发现问题时提问，同时也要根据本次审查的内容要求代码作者对某个特定问题的讲解。

2.2.3．逐项审查

对事前确定的审查内容，要逐项审查，不能因为时间不足等因素一扫而过。

2.2.4．注意气氛

实施审查时，要营造一个讨论问题、解决问题的氛围，不能把审查会搞成批判会，这样会影响相关人员的积极性。

2.3. 事后跟踪跟踪。

2.3.1. 确认发现的问题

CR结束后，对发现的问题，首先需要确定以下内容。

1. 问题点的难易程度以及影响的范围；
2. 解决问题的责任者和问题点修正结果的确认者；
3. 解决问题点的时限。

2.3.2. 修正问题责任者

对于修正问题责任者，在问题点的修正过程中，要三方面内容的记录。

1. 问题点的原因；
2. 解决问题点的对策；
3. 修正的内容。

2.3.3. 修正结果确认者

做为修正结果的确认者，必须按照事前约定的时限及时的对修正结果进行全面的确认

3．注意事项

3.1. 经常进行Code Review

1. 要Review的代码越多，那么要重构，重写的代码就会越多。而越不被程序作者接受的建议也会越多，唾沫口水战也会越多。
2. 程序员代码写得时候越长，程序员就会在代码中加入越来越多的个人的东西。
3. 越接近软件发布的最终期限，代码也就不能改得太多。

3.2. Code Review不要太正式，而且要短

忘了那个代码评审的Checklist吧，走到你的同事座位跟前，像请师父一样请他坐到你的电脑面前，然后，花5分钟给他讲讲你的代码，给他另外一个5分钟让他给你的代码提提意见，这比什么都好。而如果你用了一个Checklist，让这个事情表现得很正式的话，下面两件事中必有一件事会发生：

1. 只有在Checklist上存在的东西才会被Review。
2. Code Reviews 变成了一种礼节性的东西，你的同事会装做很关心你的代码，但其实他心里想着尽快地离开你。

只有不正式的Code Review才会让你和评审者放轻松，人只有放松了，才会表现得很真实，很真诚。记住Review只不过是一种形式，而只有在相互信任中通过相互的讨论得到了有意义和有建设性的建议和意见，那才是最实在的。不然，作者和评审者的关系就会变成小偷和警察的关系。

3.3. 尽可能的让不同的人Reivew你的代码

如果可能的话，不要总是只找一个人来Review你的代码，不同的人有不同的思考方式，有不同的见解，所以，不同的人可以全面的从各个方面评论你的代码。
但不要太多了，人多嘴杂反而适得其反，基本上来说，不要超过3个人，这是因为，这是一个可以围在一起讨论的最大人员尺寸。

下面是几个优点：

1. 从不同的方向评审代码总是好的。
2. 会有更多的人帮你在日后维护你的代码。
3. 这也是一个增加团队凝聚力的方法。

3.4. 保持积极的正面的态度

程序员最大的问题就是“自负”，尤其当我们Reivew别人的代码的时候，我已经见过无数的场面，程序员在Code Review的时候，开始抨击别人的代码，质疑别人的能力。太可笑了，我分析了一下，这类的程序员其实并没有什么本事，因为他们指责对方的目的是想告诉大家自己有多么的牛，靠这种手段来表现自己的程序员，其实是就是传说中所说的“半瓶水”。

所以，无论是代码作者，还是评审者，都需要一种积极向上的正面的态度，作者需要能够虚心接受别人的建议，因为别人的建议是为了让你做得更好；评审者也需要以一种积极的正面的态度向作者提意见，因为那是和你在一个战壕里的战友。记住，你不是一段代码，你是一个人！

3.5. 学会享受Code Reivew

这可能是最重要的一个提示了，如果你到了一个人人都喜欢Code Reivew的团阿，那么，你会进入到一个生机勃勃的地方，在那里，每个人都能写出质量非常好的代码，在那里，你不需要经理的管理，团队会自适应一切变化，他们相互学习，相互帮助，不仅仅是写出好的代码，而且团队和其中的每个人都会自动进化，最关键的是，这个是一个团队。

资料来源

• Code Reivew的执行http://www.cnblogs.com/dinofung/articles/2302957.html
• Code Review中的几个提示http://coolshell.cn/articles/1302.html
• 什么是Code Review http://www.cnblogs.com/wdpp/archive/2011/01/17/2386823.html
• web项目经理手册-Code Review http://blog.csdn.net/yzhz/article/details/1669802