代码审查规范

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