1、代码审查规范1. Code Review 目的Code Review 是一种用来确认方案设计和代码实现的质量保证机制，通过这个机制我们可以对 代码、测试过程 和 注释 进行检查。Code Review 主要用来在软件工程过程中改进代码质量，通过 Code Review 可以达到如下目的： 在项目早期就能够发现代码中的 BUG。 帮助初级开发人员学习高级开发人员的经验，达到知识共享。 避免开发人员犯一些很常见，很普通的错误。 保证项目组人员的良好沟通。 项目或产品的代码更容易维护。2. Code Review 的前提条件代码提交审核前，开发者 必须确保代码符合如下条件，审核者 需要确保所有前提条
2、件都已满足方可开始审查，同时也是审查的主要检查点。 所有代码注释清晰，语法正确，编译通过。 日志代码完整，业务日志、系统日志分开，中文描述，脱敏处理，状态变更，全部清晰明确。 测试代码覆盖全部分支和流程，暂时统一使用工具 Emma（各编译器可下载对应插件）进行 Coverage Check。 项目引用关系明确，依赖关系清晰，配置文件描述。3. Code Review 的审查范围代码的一致性、编码风格、代码的安全问题、脱敏问题、代码冗余、是否正确设计以符合设计要求（性能、功能）与设计文档相同等等。3.1、 完整性 检查（Completeness） 代码是否完全实现了设计文档中所涉及的所有流程和功
3、能点 代码是否已包含所有所需的业务日志、系统日志、异常日志，日志内容是否完整，日志文件配置是否正确。 代码是否使用缓存等，配置信息是否正确可配置。 代码中是否存在任何没有定义或没有引用到的变量、常数或数据类型等3.2、 一致性 检查（Consistency） 代码的逻辑是否符合设计文档 代码中使用的格式、符号、结构等风格是否保持一致3.3、 正确性 检查（Correctness） 代码是否符合制定的标准 所有的变量都被正确定义和使用 所有的注释都是准确的 所有的程序调用都使用了正确的参数个数3.4、 可修改性 检查（Modifiability ） 代码涉及到的常量是否易于修改(如使用配置、定
4、义为类常量、使用专门的常量类等) 代码中是否包含了交叉说明或数据字典，以描述程序是如何对变量和常量进行访问的 代码是否只有一个出口和一个入口（严重的异常处理除外）3.5、 可预测 性检查（Predictability） 代码所用的开发语言是否具有定义良好的语法和语义 是否代码避免了依赖于开发语言缺省提供的功能 代码是否无意中陷入了死循环 代码是否避免了无穷递归3.6、 健壮性 检查（Robustness） 代码是否采取措施避免运行时错误（如数组边界溢出、被零除、值越界、堆栈溢出等）3.7、 结构性 检查（Structuredness） 程序的每个功能是否都作为一个可辩识的代码块存在 循环是否只
5、有一个入口3.8、 可追溯性 检查（Traceability） 代码是否对每个程序进行了唯一标识 是否有一个交叉引用的框架可以用来在代码和开发文档之间相互对应 代码是否包括一个修订历史记录，记录中对代码的修改和原因都有记录 是否所有的安全功能都有标识3.9、 可理解性 检查（Understandability） 注释是否足够清晰的描述每个子程序 是否使用到不明确或不必要的复杂代码，它们是否被清楚的注释 使用一些统一的格式化技巧（如缩进、空白等）用来增强代码的清晰度 是否在定义命名规则时采用了便于记忆，反映类型等方法 每个变量都定义了合法的取值范围 代码中的算法是否符合开发文档中描述的数学模型3
6、.10、 可验证性检查(Verifiability) 代码中的实现技术是否便于测试 测试代码是否正确，是否覆盖所有流程4. Code Review 的步骤目前 Code Review 步骤暂定如下，试行一段时间再根据问题做调整。1. 代码编写者 和 代码审核者 坐在一起，由 代码编写者 按照设计文档中的用例依次讲解自己所写的代码和相关逻辑，可采用从前端到后台的方式，例如从 Web层-DAO 层。2. 代码审核者 在此过程中可以随时提出自己的疑问，同时积极发现隐藏的 bug；代码编写者 和 代码审核者 都要对这些 bug 记录在案，代码编写者 修改后再次提交审核，代码审核者 对应 bug 记录进
7、行回验。3. 代码讲解完毕后，代码审核者 给自己安排几个小时再对代码审核一遍。代码需要一行一行静下心看。同时代码又要全面的看，以确保代码整体上设计优良。4. 代码审核者 根据审核的结果编写代码“审核结果”并将“审核记录” 和“审核结果”提交至 GIT， 审核记录 和 审核结果 参见 附录 I 审核记录、 附录 II 审核结果。5. 代码编写者 GIT pull 并根据“审核结果” 给出的修改意见，修改好代码，有不清楚的地方可积极向 代码审核者 提出。6. 代码编写者 bug fix 等全部修改完成后提交 代码审核者 再次进行审核，通过审核则 代码审核者 更新本次审查结果并提交至 GIT， 审核
8、通过对代码不能再进行修改，任何已通过审核的代码修改必须重新进行审核流程。7. 代码审核者 把 Code Review 中发现的有价值 的问题更新到“ 代码规范“的文档中，对于特别值得提醒的问题可群发 email 或 QQ 给所有技术人员。5. Code Review 标准代码审查的基础是我们的 设计文档规范、 代码规范、 日志规范、 测试代码规范，针对新增的业务场景和设计尚未有规范对应时应先确立规范然后再进行代码审核流程。6. Code Review 注意点6.1. 经常进行 Code Review 要 Review 的代码越多，那么要重构，重写的代码就会越多。而越不被代码编写者接受的建议也会
9、越多，唾沫口水战也会越多。建议每一个功能，每一个用例完成后都可以进行审核，将大任务拆分为小任务进行。 程序员代码写得时候越长，程序员就会在代码中加入越来越多的个人的东西。 越接近软件发布的最终期限，代码也就不能改得太多。6.2. Code Review 不要太正式，而且要短忘了那个代码评审的 Checklist 吧，走到你的同事座位跟前，像请师父一样请他坐到你的电脑面前，然后，花 5 分钟给他讲讲你的代码，给他另外一个 5 分钟让他给你的代码提提意见，这比什么都好。 而如果你用了一个 Checklist，让这个事情表现得很正式的话，下面两件事中必有一件事会发生： 只有在 Checklist 上
10、存在的东西才会被 Review。 Code Reviews 变成了一种礼 节性的东西，你的同事会装做很关心你的代码，但其实他心里想着尽快地离开你。 只有不正式的 Code Review 才会让你和评审者放轻松，人只有放松了，才会表现得很真实，很真诚。记住 Review 只不过是一种形式，而只有在相互信任中通过相互的讨论得到了有意义和有建设性的建议和意见，那才是最实在的。不然，作者和评审者的关系就会变成小偷和警察的关系。6.3. 尽可能的让不同的人 Reivew 你的代码如果可能的话，不要总是只找一个人来 Review 你的代码，不同的人有不同的思考方式，有不同的见解，所以，不同的人可以全面的从
11、各个方面评论你的代码。 但不要太多了，人多嘴杂反而适得其反，基本上来说，不要超过 3 个人，这是因为，这是一个可以围在一起讨论的最大人员尺寸。下面是几个优点： 从不同的方向评审代码总是好的。 会有更多的人帮你在日后维护你的代码。 这也是一个增加团队凝聚力的方法。6.4. 保持积极的正面的态度程序员最大的问题就是“自负 ”，尤其当我们 Reivew 别人的代码的时候，我已经见过无数的场面，程序员在 Code Review 的时候，开始抨击别人的代码，质疑别人的能力。太可笑了，我分析了一下，这类的程序员其实并没有什么本事，因为他们指责对方的目的是想告诉大家自己有多么的牛，靠这种手段来表现自己的程序
12、员，其实是就是传说中所说的“半瓶水”。 所以，无论是代码编写者， 还是代码审核者，都需要一种积极向上的正面的态度，编写者需要能够虚心接受别人的建议，因为别人的建议是为了让你做得更好；审核者也需要以一种积极的正面的态度向编写者提意见，因为那是和你在一个战壕里的战友。记住，你不是一段代码，你是一个人！6.5. 学会享受 Code Reivew这可能是最重要的一个提示了，如果你到了一个人人都喜欢 Code Reivew 的团队，那么，你会进入到一个生机勃勃的地方，在那里，每个人都能写出质量非常好的代码，在那里，你不需要经理的管理，团队会自适应一切变化，他们相互学习，相互帮助，不仅仅是写出好的代码，而
13、且团队和其中的每个人都会自动进化，最关键的是，这个是一个团队。7. Code Review 操作目前我们将 Code Review 分为两个阶段，开发互审 和 上级审查 两个阶段。7.1 开 发互审任意两名开发人员（建议不要固定配对，避免思维定势）进行交叉代码审查， 代码编写者 准 备所开发的代码相关的全部资料列表，包括需求、设计文档、代码工程、类、方法、配置文件、数据库修改、数据修改等全部资料的版本号等详细信息，向 代码审查者 全面介 绍代码的目标和设计实现。代码审查者 按照需求文档、设计文档、开发规范进行代码（业务、日志、测试）审查， 代码审查者 将审查结果提交至 GIT，出现的问题由 代
14、码编写者 进行修改并由 代码审查者 复审，复审结果提交至 GIT 保留。代码审查者 对所审查的代码负责。7.2 上 级检查开发互审完成后，由上级进行上级审查，流程与开发互审相同，对于三次复审仍未通过的代码需要 代码编写者 组内进行检讨问题原因，并书面列出改进计划。7.3 冲突解决当开发互审时对于检查内容出现争议时由上级进行协调解决或逐级向上协调解决。 当上级审查时出现争议时逐级向上协调解决。所有问题解决原则为公司利益、团队利益、业务需求、设计文档、规范文档等为参考标准。附录 I 审核记录审核记录如同修改记录一样，直接记录入代码头部，代码审核者修改审核记录后提交代码至 GIT 参考即可。之后的审
15、核可以基于两次审核间的变更利用对比工具进行增量审核。 可参考如下示例类：ngp_common/src/main/java/com/heepay/file/FileUtils.java代码示例：/* * * 名称：文件操作工具 类 * * 创 建者： 王 晓 * 创 建 时间 ： 2016-06-21 * 创 建描述： 实现 文件的 创 建、 删 除、复制、压缩 、解 压 以及目 录 的 创 建、 删 除、复制、 压缩 解 压 等功能 * * 修改者： 李宗杰 * 修改 时间 ： 2016-08-08 * 修改描述：添加注 释 和代 码审 核信息 * * 修改者： * 修改 时间 ： * 修改描
16、述： * * 审 核者： 侯建春 * 审 核 时间 ： 2016-08-08 * 审 核描述：格式可以 * 一行写不下再次一行 * 再来一行 * * 审 核者： 李宗杰 * 审 核 时间 ： 2016-08-08 * 审 核描述： 审 核不通 过 ， log 没有使用 log4j2 * * 审 核者： * 审 核 时间 ： * 审核描述： * * */附录 II 审核结果审核结果建议以表格的形式描述，每个问题分别列出，可以通过标注行号来具体指明位置，给出合理的修改意见并说明标准。为了方便记录和查询以及代码编写者修改和复审，建议审核结果写入 commit message 中，由于 commit
17、message 只能提交文本，我们以软表格的形式描述。对于 commit message 的书写规范，查看参考。格式：docs(代码审核): 审核通过 docs(代码审核): 审核失败 1. 问题名称 问题：问题内容描述 建议：修改建议描述 行号：涉及到的代码行号，如有可列出 2. 问题名称 问题：问题内容描述 建议：修改建议描述 行号：涉及到的代码行号，如有可列出 示例：docs(代码审核): 审核失败 1. 日志不符合规范 问题：没有使用 log4j2，日志不规范 建议：修改使用 log4j2，包括包引用和代码修改 行号： 53 行 2. 命名不符合规范 问题：log 命名不符合规范 建议：修改为 logger 行号： 53 行
