Everyone in R&D knows the importance of code reviews. Tencent code reviews are also getting more and more attention. As a member of Tencent's proprietary cloud platform development, I participated in a lot of code reviews. It is obvious that effective code reviews can not only Improving the quality of the code can promote team communication and collaboration, and establish higher engineering quality standards, which has important value for both individuals and teams. This article will share my personal views on why to do code review and how to do code review effectively.
Why do code review
Why do you need a code review? I believe everyone has a more consistent answer. You can also find a lot of articles in a Google search. Here is a brief summary:
1) Improve code quality
This is the original intention of the code review and the most direct value of the code review. Reviewers put forward various possible improvements to the code based on their own experience, way of thinking, and the perspective of the problem, so as to form a better code and product quality.
We know that the later a product problem is proposed to solve it, the more expensive it will be. There will be more and more people involved and processes to go through. The code review can be said to be one of the most effective ways to solve the problem in the early stage. Solving even a small problem in the code review can avoid a lot of subsequent troubles.
2) Form a unified high quality standard for the team
An effective code review will eventually establish a unified quality standard within the team, and will form a higher standard as the team members learn from each other and promote. Participants will propose improvements from different angles based on specific issues during the code review process, and finally make the current best choice and form a consensus. With the effective progress of the code review, team members will consciously pay attention to the quality of the code, thereby forming increasingly higher de facto quality standards.
3) Rapid personal growth
Through effective code reviews, both Author and Reviewer will grow. During the review process, participants will have in-depth discussions on specific issues, no matter how to write clean code, how to think about the problem more comprehensively, and how to best To solve problems well, all participants can learn from each other and improve each other. Discussions through specific code implementation are often the most in-depth and effective. Code review is one of the most important ways for developers to improve code capabilities.
Some people think that the code review is that the Reviewer helps to find bugs in the code . In fact, the code review should not be a one-way process, but a two-way communication process . While the Reviewer helps the Author put forward suggestions for code improvement, it is also to the excellent Author. The process of learning. We all know that an effective way to improve code ability is to read excellent project code, but reading project code is not small, which is why most people do not implement it, and review the code of senior colleagues, we are reading the code At the same time, the ability to communicate directly and effectively is a fast and effective way of learning, especially for developers who are not yet rich in development experience.
How to do code review
2.1. When to launch Review
In the code review, Author needs to realize: Reviewer time is expensive . Therefore, before officially inviting the Reviewer to initiate a code review, the Author has several points to note, which can improve the efficiency of the code review and save the Reviewer's time.
2.1.1. MR (Merge Request)
Also known as PR (Pull Request), MR is where we conduct code reviews. It records specific changes to the code and the specific discussion process of participants. A good MR should do the following:
Single : An MR should only solve a single problem, whether it is fixing a bug or implementing a new feature. Authors should avoid code changes with different intentions in an MR. A single MR can help the Reviewer quickly understand the motivation of code changes, and can conduct reviews in a targeted manner.
Short : MR should be as small as possible. For example, if a feature introduces many changes, it is necessary to consider whether it can be disassembled into several independent pieces of implementation, and MR should be mentioned separately, such as interface definition, interface implementation, logical docking, etc.
Details : The details mentioned here mean that MR should describe its background and motivation as much as possible. It can be reflected in the MR description, or it can be connected to a specific issue or tapd list. The goal that needs to be achieved is that when other people open a MR, they can know the background and motivation for making this change.
2.1.2. Commit Message
I looked at a lot of existing project codes before and saw that many Commit Messages were written relatively simply, such as a series of "update" and "fix". From these Commit Messages, you can't see any changes at all. Think about it. If you want to locate a previous change later, where should you start.
At present, the Commit Message specification is relatively common with the Angular team's specification , and from this it has derived the Conventional Commits Specification . You can refer to this Specification to agree on the Commit Message format specification.
<type>(<scope>): <subject><BLANK LINE><body><BLANK LINE><footer>
Approximately three lines:
【Title line】 Required, describe the main modification type and content.
[Subject content] Describe why the modification was made, what kind of modification was made, and the idea of doing so, etc.
[Footer Notes] Put Breaking Changes or Closed Issues
Where type is the type of Commit, which can have the following values:
feat: new features
fix: modify the bug
refactor: code refactoring
docs: Documentation update
style: Code format modification
test: Test case modification
chore: other modifications, such as build process, dependency management
The scope represents the scope affected by Commit, such as ui, utils, build, etc., which is an optional content.
The subject is the summary of Commit, and the body is the specific content of Commit.
E.g:
fix: correct minor typos in codesee the issue for details on typos fixed.Refs #133
Commit Message can configure the template in git, so that the template can be displayed in vim, and there are tools to help us generate and constrain Commit Message, such as commitizen/cz-cli, which will not be described in detail here.
2.1.3. CI Pass
CI (Continuous Integration), continuous integration can help us automatically discover many basic problems in the code. With appropriate static code inspection (lint) configuration and good unit test coverage, CI can effectively improve the quality of the code. Many people underestimate the ability of static code inspection. In fact, static code inspection in common languages can help find many bugs and hidden dangers. For the Go language, you can configure golangci-lint to do code inspection. The unit test can formulate corresponding standards according to the actual situation, such as a coverage rate of 60%, and the key code logic is as comprehensive as possible.
Before submitting the code review, you need to ensure that the CI execution is passed . This is also to save the Reviewer's time. Things that can be solved automatically, try not to let the Reviewer do it, and the Reviewer finds that the MR that has not passed the CI can also ask the Author to solve the CI problem first.
2.1.4. Self-Review
Our general code review is to find someone else to do the review, in fact, the responsible Author also needs a simple review by himself before inviting others to code the review, that is, Self-Review.
The purpose of Self-Review includes:
Found those obvious oversights, such as unnecessary traces left during the code debugging process, such as fmt.Println(...), accidentally commented out code.
Questions that have been raised many times by the Reviewer before.
Whether the Commits are normal, and whether irrelevant Commits are brought into the MR in the case of multi-person collaboration.
Whether the Commit Message is appropriate.
Self-Review is a very fast process. From my personal experience, it usually takes 1-2 minutes to complete, so I recommend that you develop the habit of Self-Review.
2.2. Who should I review?
From the purpose, the Reviewer can be considered from the following aspects:
Improve code quality. So first, you should find R&D personnel closely related to code changes to participate in the Review, such as developing a certain function, a certain project together, or participating in the program design discussion and giving valuable opinions.
Get opinions. Look for senior R&D with relevant experience to help review, such as senior R&D in Java language, research and development of the same or similar systems/functions that have been written.
Form a consensus. If it involves interface changes between different teams or modules, or other changes that will affect others, you can invite the interface people of related teams or modules to participate in the Review to form a consensus on the changes.
Quality control. For important code bases, stricter quality control may be implemented. If necessary Reviewers are set, these Reviewers will also participate.
Change notification. In many cases, a code base may only be maintained by one person. If some special changes are made, it is difficult for others to find out. Therefore, when doing something important but not straightforward to understand, it is best to inform the relevant R&D so that they can roughly know what is going on.
2.3. What do you review?
There are often Reviewers who get the MR and don't know what to review. In fact, no matter how deep you are in the corresponding project, you can review the code. Different people are encouraged to help the review from different depths and angles. Code Review has no fixed form, it is more like an art, and the only way to improve is to actually participate.
When reviewing, you can start with the following aspects:
1) Simple Review
In the case of CI passing, the simplest review method may only need to be this:
Reviewer: Has it been verified in the actual environment?
Author: Of course verified
Reviewer：LGTM
This is a reminder review. Confirm one sentence: whether it has been verified in the environment , or further important acceptance points that can be thought of to confirm it again. Even the simplest review is actually valuable. It is difficult for us to guarantee that all R&D will actually verify the changes made in the environment before MR, and it is also difficult to guarantee that unit testing and e2e testing can cover everything. Under the circumstances, it is basically impossible for the Reviewer to run it on the environment by itself. Letting the Author confirm is actually reminding the Author to ensure that the changes are at least real and effective, especially for some released versions of Bugfixes, be sure to remind the actual self-test to pass.
Similar reminders also include: whether the relevant documents (external) have been updated accordingly, whether this change will cause compatibility issues, and whether performance affects. Their essence is to remind Author to think about the problems they may have missed.
2) Regular Review
Code reviews generally start with code style, variable naming, and grammar uniformity. Of course, these should be guaranteed by more automated means such as CI, but it is still necessary to pay attention to the premise that the related process is not perfect.
In addition, code readability, code robustness, and code scalability are all the points of concern during the review. Every focus depends on the actual experience of the Reviewer. Here are just a few examples:
{Code readability}
The code is written for people to see , because there is no code that does not need to be maintained. Whether it is the author's subsequent maintenance code or someone else takes over the code, it is very necessary to quickly understand the code logic.
When reviewing the code, pay attention to the following points:
Whether the naming of variables and methods is appropriate and whether they truly reflect their purpose, a lot of information can be found on the Internet.
Whether the implemented logic can be replaced by a ready-made library. If there is a mature library you can use, try not to implement it yourself, because unnecessary bugs may be introduced. From my personal point of view, conciseness (less code in the vernacular) is a very important indicator of readability.
Regarding notes. Code comments don’t ask for too much, but are effective. I have experienced the age when code comments are required to reach at least 30%. Now it seems that relying too much on comments is actually a lack of confidence in code quality. Good code should try to be self-explanatory. . In the actual process, I can occasionally see that the code logic is actually clear, but I have annotated it in English with poor sentences. In the end, I understand the code to understand what the comment says. Therefore, unnecessary comments can be removed when reviewing.
Appropriate comments should be made for areas that are difficult to understand. If there are special treatments, special constants, or logic that does not conform to general usage in the code, special comments are needed.
Organization of the code. Good code should have better encapsulation and hierarchy, so that the code looks clear and clear, such as DAO layer, Service layer.
{Code Robustness}
Does the code change affect other functions?
Whether user parameters are to be checked carefully.
Is there a possibility of Panic (in terms of Go).
Will it break API compatibility.
{Scalability}
Is the current implementation compatible with similar expansion requirements in the future? For example, when adding new interfaces, APIs, or adjusting parameters to solve a problem, you can consider whether other similar situations will occur in the future. To give a few examples:
Suppose we need to define an API interface to obtain certain information of a user, such as contact information, etc. The API we define cannot only return this information, but should return all user-related information.
Suppose I want to define a parameter, although the current definition is a single element, such as string, int, but whether it will involve multiple elements in the future, whether it is defined as []stirng, []int is better.
Here are just a few limited examples. In the actual review process, the Reviewer can put forward optimization suggestions from various angles based on its own experience. Generally need to focus on:
Where you can't understand or doubt.
Break your routine.
Complicated place.
2.4. How to proceed
During the review process, the Reviewer is encouraged to comment boldly, and directly express what you don’t understand or feel inappropriate. The author also needs to give feedback to each MR comment , whether it is to start a discussion or simply give an OK Effective feedback.
The review process can be:
After the completion of various confirmation tasks, the Author initiates a Review. If it is urgent, you can send a message to an important Reviewer to ask for help.
Reviewer should first confirm the background and purpose of the MR after seeing the MR. If it is not clear and cannot obtain the information from the MR, it is best to communicate directly with the Author.
Reviewer puts forward his own suggestions or questions directly on MR.
The Author gives feedback on each Comment and starts the necessary discussion.
Complex topics can be discussed offline to improve communication efficiency.
After the Author has processed all the Comments and modified the code, you need to @ the relevant Reviewer in the MR to inform that all optimizations have been submitted. If the time is urgent, you can also directly communicate with the Reviewer.
The Reviewer confirms that there is no problem. Approve the MR. Generally, the simple reply is LGTM (Lood Good To Me). You can also praise the Author's work, such as "God Job".
After Approve, who will merge the MR depends on his own choice.
If the Reviewer provides a lot of useful suggestions to help optimize the code, Author can also politely thank the Reviewer.
2.5. About Comment
The code review is to a large extent picking faults on the code, and it is generally expected that the more picks the better, but the code is written by the Author, and in many cases it will more or less cause discomfort to the Author. So you need to pay attention to the wording as much as possible when commenting, especially some subjective things, which are generally given in a suggested way. Of course, for issues of principle, we must adhere to the quality standards, and even Deny can directly drop MR.
In addition, the participants should not be stingy with your excellent words . Whether it is Author or Reviewer, if you find a good place or a good suggestion in the Review, please give the other party affirmation and praise, which will help the Review to proceed effectively.
2.6. What mentality should participants have
2.6.1. Author
The first thing to be clear is that the Author is responsible for the quality of the code, so you should look at the Reviewer who insists on helping you review the code with a grateful heart, because not all the Reviewers you add have the time and energy to help you improve the code quality.
It is also officially because Author is the owner of your own code, so don’t rely on Reviewer to help you guard the gate of code quality, such as "Why didn't you see it during the code review", "Isn't this what you suggested me to do?" Don't say anything. Reviewer just helps you improve the code quality, so we have to do all the work we should do. For example, the meticulous Reviewer may directly suggest code optimization in some cases, and the optimized code snippets are posted in the Comment, and the Author cannot directly assume It must be able to work normally, but it should be fully verified.
Don’t be resistant to the Comments given by the Reviewer. You can tactfully reject suggestions that you find unreasonable, or explain in detail your own views and the reasons for doing so. Sometimes a suggestion that you find unreasonable may represent a new perspective, or it may represent the lack of the Reviewer's own code capabilities, no matter which one, whether the Author or the Reviewer has been improved in the end, it should be a good thing.
2.6.2. Reviewer
Reviewing code is not only a process to help improve code quality, but also a process for Reviewer to improve its code and communication skills. Therefore, we should maintain a learner's mentality while reviewing, not only to find the defects in the other party's code, but also to work hard to find the highlights in the code. Remember to simply review the code with a faulty mentality.
Many Reviewers hesitate when writing Comments, worrying that their questions or suggestions are "stupid", so they hesitated after reading the code and holding a lot of doubts and finally left nothing. In fact, you don’t need to have any mental burdens when reviewing the code. If you have any doubts, unclear points, or any ideas of your own, you can directly put them forward. Sometimes a simple Comment may arouse Author and yours. Comment Irrelevant new ideas. Besides, even if you didn't help Author improve the code, wouldn't it be a good thing to let Author help you improve your thinking?
Reviewer does not need to pay attention to its own "output". It does not have to ask a lot of questions to make a good code Review. Author code is well written and it is normal. If you think the code is okay from your point of view, be bold Give it to LGTM or even Approve.
Welcome to follow our video number: Tencent programmer
Latest video: What day is October 24?