如何编写代码审查文档

一、前言

代码审查(Code Review)是开发流程中非常重要的一个环节，可以帮助发现并改正代码中的错误，提高代码质量，也是共享知识、熟悉代码的好机会。

最近功能开发完毕需要做代码审查，发现国内很多公司不强制要求编写代码审查文档，很多人并不会认真思考代码审查文档需要包括哪些内容，大概该怎么写。
我的看法是，虽然一般公司不要求写代码审查文档，但是最好自己能够准备一个，方便线下代码审查时不遗漏重点，跟踪代码审查的修改情况等。
本文简单给出一个简单的参考。

二、代码审查文档

2.1 文档包括的内容

在准备代码评审之前，你需要做如下准备：

1. 需求文档：如果项目基于特定的需求文档，也应将需求文档一并提交，帮助审查者理解你的实现目标。
2. 设计文档：如果有对应的设计文档，将其一并提交。设计文档可以帮助审查者理解你的设计思路，掌握代码的整体架构。
3. 代码审查清单：列出你想要同事关注的重点，包括新的设计模式，核心算法，重要的类或者函数等。
4. 单元测试和集成测试代码：对于每一个功能，都应该编写相应的单元测试或集成测试代码，这能够帮助审查者验证功能是否正常。
5. 问题和改进意见收集表：准备一张表格，可以在代码审查时记录代码审查人员提出的问题和给的改进意见，并跟踪自己的修改情况等。

通常我会将项目的需求文档、设计文档、代码审查清单（仓库、分支、核心代码、核心单测、单测覆盖率等）、改进意见收集表都记录在文档中。

2.2、代码审查清单

给出代码的仓库地址和代码的分支，项目代码相当于 Master 的diff 链接等。

仓库
分支
Diff 链接

然后给出核心代码清单：
（1）可以从功能方面划分，如每个功能对应的关键代码位置等。

序号	功能描述	核心代码引用	审查重点
1	资讯的缓存功能	FeedsCacheManager	重点介绍 缓存 Key 和过期时间
2	资讯推荐功能	FeedsFacade.recommend	推荐的打分逻辑
3

（2）也可以从层次方面划分，如重点的 Facade 、 Service 、Dao、 工具类代码位置等。

序号	功能描述	核心代码引用	审查重点
关键入口	功能1	FeedsFacade.xxx
	功能2	FeedsFacade.yyy
核心逻辑	xxxx	XXXService.yyy
核心工具类
核心单测

2.3、问题和改进意见记录

以下是一个简单的【问题和改进意见记录】模版。这个模版可以根据实际需要进行调整：

序号	文件名/类名/方法名	问题描述	改进建议	问题严重级别	提出人	进度
1	ExampleClass.java	变量命名不规范，使用了单字符命名	使用有意义的变量名，如： employeeName 代替 n	低	John Doe	[ ] 完成
2	ExampleMethod	方法过长，超过100行	尝试拆分这个方法，每个方法应尽可能完成一个具体的功能	中	Jane Doe	[ ] 完成
3	ExampleClass	缺少单元测试	添加相应的单元测试以保证功能正确性	高	John Doe	[ ] 完成

在这个表格中：

• "文件名/类名/方法名"是指出问题的具体位置。
• "问题描述"是对问题的简要描述。
• "改进建议"是对如何改进代码的具体建议。
• "问题严重级别"表示问题的重要程度，可以依据问题的性质和影响程度进行分级，如：低、中、高。
• "提出人"是指出这个问题的人。

这只是一个基本的模版，你可以根据自己的需要进行调整和扩展。

三、总结

其实准备代码审查文档并没有浪费很多时间，线下代码审查时自己能够非常清楚自己代码的重点，就可以避免遗漏要点，审查效果会更好。

代码审查文档也有助于功能开发时间过长之后，快速找到功能的入口、核心代码的位置等。
如果周围的人都不编写代码审查文档你写对应的文档，如果被主管“发现”或许会有更多“机会”。
总之，希望大家尤其是大的项目开发完毕进行线下代码评审时积极编写代码审查文档，方便自己也方便他人。