First, the benefits of the Code Review
Want to do Code Review, must be allowed to participate engineers are fully aware of the benefits of Code Review
1, mutual learning, achievement each other
Whether experts gathered architect team, or to CURD-based business development team, our technical capabilities, experience is different.
By Code Review, to achieve the same function, experienced engineers can provide reasonable suggestions to optimize the inexperienced engineers. Inexperienced engineers can read high-quality codes of best practices related to the use of technology to learn quickly. If you considerable technical strength, may refresh each other think.
Do you have an apple and I have an apple, to exchange with one another, we still have an apple; but you have an idea, I have an idea, to exchange with each other, we have two ideas, or even more.
2, knowledge-sharing, automatic mutual support
In most of the team, especially the use of service architecture and micro-architecture service team, usually a developer is responsible for more than one service / Project (Project), if no Code Review, then the architecture of knowledge involved in the project, or business knowledge, it only exists in the project implementation process output schema document, as well as core processes, the function of the documents.
Documentation can help engineers understand the situation other service / project, but other engineers usually do not take the initiative to read these documents, when they do want to maintain code written by another engineer, document integrity is often not a good initial results, with documents match code implementation will fall.
Code Review process, the logic of the code is to read the description of the submitter, see code implementation is consistent with the description. At this time, Reviewer must read the documentation, dissemination of knowledge is better, it is basically only one person does not appear to understand the situation of a project.
3, unified style, improves quality
If you give points about code quality grade, then it should be:
Can compile -> function correctly -> can be tested by -> easy to read -> easy to maintain. So, by the Code Review of the code easy to read at least up to this level.
To achieve easy to read, as long as there is not that Code Review this link on it, but also related specifications, so that everyone works in the same style, coding style to write code and build the project. Unified style on the one hand so that we maintain the project or whether it is to read the code, do not have to adapt to each other's coding practices, in addition to the Reviewer is a Code Review of the fundamental basis.
Code Review is not a necessity Bug found, but the accessories. As for the low-level issue / bug to the code scanning tool on it, this is not the duty of the Code Review.
Second, to promote the implementation of Code Review landing
1, the selected tool
Code Review tools can be used to do a lot, here introduces the relatively mainstream Gerrit, GitLab
- Gerrit
Gerrit is Google's open source code review tool, Gerrit is also a built-based Git version management tools, Gerrit support other Git repository of code to do synchronization with Gerrit own warehouse. All of the code review of operations and access control are all in their own warehouses Gerrit conducted.
Gerrit for code review is to build, so the code review authority control, and the function is very perfect.
Gerrit is mandatory CodeReview to support Develop, Reviewer, Approver three roles to support different configuration for each of CodeReview Project personnel and permissions.
If you want to do some statistical reports based on data Gerrit, Gerrit directly access the database, if the function does not meet the requirements, because it is open source, Java development team can have their own custom
In short, Gerrit Code Review of the function is very perfect, the disadvantage is probably the UI, interaction too old and weak management platform.
- GitLab family
GitLab is built Git source code management system based on GitLab built GitLab.com is second only to GitHub.com online source code management platform.
GitLab points GitLab CE (Community Edition) and GitLab EE (Enterprise Edition) two versions, open source community edition will feature relatively little weak, but free to use, free to deploy, customize and maintain. Enterprise Edition is powerful, but requires a fee.
GitLab can be by MergeRequest Review code, can be done to force CodeReview, community supports Develop, Reviewer two roles, Enterprise Edition supports Develop, Reviewer, Approver three roles, can give to the project / group is assigned different roles (Master, Developer) to control the permissions Merge code.
If you need to do some statistical reports based on data GitLab, GitLab provides a very friendly restful API, if you want customization, it is recommended to do through the API customization tools, programming languages without restriction.
GitLab of Gerrit Code Review feature is not fully functional, but the documentation that came with GitLab function, and GitLab sound management background to be better than Gerrit, if to do CI / CD, Community Edition is the best choice for almost GitLab
- Gerrit VS GitLab comprehensive comparison
|
tool |
Access control |
UI alternately |
Source Control |
Maintainable |
Statistics |
Tools supporting |
|---|---|---|---|---|---|---|
|
Gerrit |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ |
⭐ ⭐ ⭐ |
⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ |
|
GitLab Community Edition |
⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
|
GitLab Enterprise Edition |
⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ ⭐ |
⭐ ⭐ ⭐ ⭐ |
Gerrit Code Review strengths only control, GitLab a more comprehensive, but GitLab Enterprise Edition for a fee. So, in all, I recommend GitLab Community Edition
Based CodeReview tutorial GitLab of: https://ken.io/note/gitlab-code-review-tutorial
2, the development of the development of norms
No rules, no execution. Rules first is the development of norms.
Specification recommendations included:
- Engineering Practice (engineering structures, stratification and Naming, etc.)
- Naming convention (interface, class, method names, variable names, etc.)
- Code format (brackets, space, line, indent, etc.)
- Notes norms (provisions necessary comments)
- Log specification (reasonable logging necessary)
- It recommended and not recommended for a variety of code samples
If a small number of teams, lower project complexity, can develop their own specifications. After all, the team is the best fit.
If the team has a certain scale, and will continue to expand, it is recommended to be developed according to the specifications of manufacturers, or used directly.
Java Development Manual: https://github.com/alibaba/p3c undefinedGoogle Code Style Guide: https://zh-google-styleguide.readthedocs.io (covering: C ++, Python, etc.)
3, specification development process
- Code Review embodiment determines link
image
CodeReview proposal is submitted before the test on the code, which is the developer to complete the self-test code development and code that will be submitted to the Code Review when the testing branch. After all, if the test carried out by the Code Review and then, if necessary code changes, is bound to increase the workload of the test, and even affect the project schedule. Also, or pressure on the line against the project, simply "later" the
Git Workflow with generic terms, that is to be placed when Feature Code Review Develop branch into a branch.
- Normative role behavior
|
Roles |
rule |
|---|---|
|
Developer |
1, the function of submission must be complete 2, fine-grained default submitted (independent of the method / function / module unit). For coarse-grained submitted in advance to communicate with the Reviewer confirmation 3, Commit Message to be clear description of the change theme necessary, attach documentation requirements / design documents as a link or file |
|
Reviewer |
1, does not allow self-Review and Merge Code 2, Review by not need to explain why with the Developer before playing back and agree on 3 reasons Review not to fight back through the need to clearly fill 4, when a single Review long to be under 23 minutes to 2 within hours to complete (special circumstances, please explain why) |
|
Approver |
1, approval is not required to specify the reason by 2, approving long need to control in less than 1 hour 3, for the release of non-quality problems, need to continue to follow up |
Such norms, mainly in order to:
- Size Control Code Review submitted code
- 控制单次Code Review的时间
- 提升Commit/MergeRequest描述的质量，减少沟通成本
这样，我们就可以通过细粒度高频次的方式尽可能利用工程师碎片化的时间进行Code Review，一定程度上保证Code Review的效率。
毕竟，粗粒度甚至是集中式的Code Review，时间上难以把控。发现了问题的时候，修复的成本也往往更高。
3、分享与统计
有了工具、开发规范、流程规范，就可以指引参与的工程师参与Code Review，那么我们也要对Code Review的过程以及结果进行检验，毕竟不进行检查/验收的规则，是无法达到预期效果的。
Code Review毕竟不是数学题，我们无法通过简单的计算去验证。所以我们要通过侧面验证，来帮助Code Review的执行
- 定期分享
我们是期望CodeReview可以让工程师之间互相学习的，那么对于一次Code Review通常只有参与的2-3个工程师有互相学习的机会，那么在这个过程中学到的知识，定期的分享出来，既可以加强知识的流动，又可以检查大家究竟有没有在Code Review过程中学习到知识，或者有没有认真的进行Code Review
至于分享的内容，可以是开发规范中的范例代码，也可以是规范中的正例代码，也可以是针对某个功能实现的最佳算法/最佳实践，也可以是Code Review过程中的争议代码，也可以是自己踩过的坑。
总之，Code Review之后的代码分享，不但可以加强知识的流动，还可以检验Code Review的效果。
- 数据统计
为了在一定程度上保证Code Review的效率，我们在规范里是要求参与的工程师：
- Developer控制提交Code Review的粒度，或者控制每个Commit的粒度
- Developer要准确清晰的描述所提交的代码
- Reviewer&Approver要在规定时间内完成Code Review
这些情况纯粹靠人工是无法检验的，还是需要有一定的数据统计。
如果用Gerrit，可以查询Gerrit的数据库，里面会有Code Review的信息，
如果用GitLab，可以通过WebHook或者restful API获取Code Review信息
我们可以做成报表，来展示Code Review的情况：
- 每人每周Code Review所消耗的时间
- 每人每周被Code Review所消耗的平均时间
- 超过规定时间的Code Review情况
- 代码提交描述字数过少的情况
- 等等（根据自己的需要来）
以上情况只是Code Review的侧面反馈，用来帮我们发现Code Review执行过程中可能出现的问题。不过，出现问题并不意味着Code Review的质量/效率一定受到了影响。
比如，工程师A被Code Review的耗时是团队内最高，有可能是有某次代码是周五晚上提交的CodeReviw，这单次CodeReview的耗时就会超过48小时。也有可能是对应的Reviewer是团队新人，要通过相关业务项目了解对应Project的承担的职责及代码，这是个学习的过程，自然耗时加长。
又比如工程师B提交的代码描述文字过少，可能就是中间件团队对某些基础组件进行升级，或者安全团队要求升级某个依赖的开源组件，以修复某个安全漏洞。
但是通过这种的数据，可以让Code Review的情况直观的展示出来。来发现大家执行过程中需要优化的事项， 不断帮助大家完善规则，做好执行。
三、保证Code Review质量的关键
1、工程师对研发规范的认真学习
无论Code Review的工具以及流程是怎么样的，都少不了开发规范作为支撑，毕竟我们期望Code Review达到的效果之一就是，团队中的工程师可以写出像规范中描述那样的高质量代码。
工程师对研发规范的掌握程度，决定了自己编码代码的质量，也决定了自己Review通过的代码的质量。所以，无论如何，加强对研发规范的学习和理解，都是保证Code Review质量的重中之重
2、资深工程师的认真对待
Code Review目的是帮助工程师交流和学习进步的。无论是技术能力还是编码习惯，亦或是业务知识。无论规则怎么制定，终究还是需要参与的工程师来执行，如果大家互相睁一只眼闭一只眼，互相降低要求，那么执行的效果一定会打折扣。
虽说三人行必有我师，但收益最大的一定是经验(技能/业务知识)尚浅的工程师，收益最低的一定是团队中最资深的工程师。而恰恰经验尚浅的工程师的收益大部分都要来自资深工程师的付出。
所以，一定要跟资深工程师最好沟通，让他们严格要求，不能对经验尚浅的工程师放水，以帮助他们提升编码能力以及业务知识。
这也可以减少甚至避免他们为经验尚浅的工程师的代码“善后”。
四、备注
附录
- Java开发手册：https://github.com/alibaba/p3c
- 基于GitLab的CodeReview教程：https://ken.io/note/gitlab-code-review-tutorial
- Google代码风格指南：https://zh-google-styleguide.readthedocs.io
- Jenkins+Sonar执行代码扫描：https://ken.io/note/jenkins-maven-java-sonar-integration
本文首发于我的个人博客：https://ken.io/note/how-to-do-code-review-in-a-team