Google was founded in 1998 to start with search and has been developing for 21 years so far . Over the past 21 years, Google has continued to innovate, developed seven products, has more than 1 billion active users, and Google's engineering culture has always been considered excellent and special. Recently, Google has open sourced the code review specification that it has been using internally. InfoQ has translated and organized it and shared it with developers to see how Google engineers review code.
Code Review Criteria
The main purpose of code review is to ensure that the overall quality of the codebase improves over time, and all code review tools and processes are designed to achieve this goal.
To achieve this goal, a series of trade-offs must be made. First, the developer's development task must progress. If they don't commit improved code, the quality of the codebase won't improve. Also, if reviewers are too strict, developers have no incentive to make continuous improvements.
The role of the reviewers is to ensure the quality of each CL (change list), ensuring that the overall quality of the codebase does not degrade over time. This is a daunting task, as the overall quality of the codebase often degrades with a small decrease in the quality of each commit, especially when the development team is pressed for time and feels that it has to cut corners to complete the delivery.
Reviewers take responsibility for the code they review, ensuring that the codebase remains consistent and maintainable.
The following are guidelines that can be used in code reviews:
In general, if CLs get to the point where they improve the overall code quality of the system, they'll pass, even though they may not be perfect.
This is the overriding principle of all code review guidelines.
Of course, there are exceptions. For example, if the CL includes features that the system doesn't need, the reviewers can refuse to let them pass, even if the code is well written.
There is no "perfect" code in this world, only better code. Reviewers shouldn't ask developers to fine-tune every tiny part of the CL, but rather make a trade-off between meeting the requirements and the importance of the change. Reviewers should not strive for perfection, but for continuous improvement. If a CL improves the maintainability, readability, and understandability of the system as a whole, it shouldn't be delayed for days or even weeks just because it's not "perfect" enough.
Reviewers should provide advice on what could be better for developers. But if these suggestions are not very important, prefix them with something like "Nit:" to let the developers know it's just an improvement suggestion, or they can choose to ignore it.
guide
One role of code reviews is to impart knowledge to developers, such as knowledge about a language, a framework, or general software design principles. Sharing knowledge is an integral part of improving system code quality. Note, however, that if your advice is purely educational and not all that important to meet the criteria described in this article, then preface it with "Nit:", or otherwise tell the developer, They don't necessarily have to address these issues in CL.
in principle
-
Objective technology and data are more important than personal opinions and preferences.
-
In terms of code style, you can refer to the Google Style Guide ( http://google.github.io/styleguide ). Anything that doesn't appear in this style guide (like spaces, etc.) is a matter of personal preference. The code style should be consistent with the original code. If the code style is not specified before, the code submitter's code style can be used.
-
Software design is never just a matter of style or personal preference. They are built on some basic principles, so we should base our trade-offs on those principles, not just personal preference. Sometimes there are multiple solutions to a problem, if the developer can demonstrate (through data or based on sound engineering principles) that several solutions are equally valid, then the reviewer should accept the developer's choice, otherwise it should be based on the software Design criteria principles to make decisions.
-
If no other principles apply, reviewers can ask developers to be consistent with the current codebase, as long as it doesn't compromise the overall code quality of the system.
conflict resolution
When conflicts arise during a code review process, developers and reviewers first try to follow this article, the CL Author Guidelines ( https://google.github.io/eng-practices/review/developer/ ), and the Reviewer Guidelines ( https: //google.github.io/eng-practices/review/reviewer/ ) for consensus.
If consensus is difficult, reviewers and developers can have face-to-face meetings or video conferences instead of just trying to resolve conflicts through code review comment boards.
If that doesn't resolve the issue, then consider escalating the issue for a wider team discussion. Involve the team lead, ask the code maintainer to make a decision, or ask the engineering manager for help. Don't let the CL hang around just because the developers and reviewers can't agree.
What do you need to pay attention to in code review?
design
The most important part of a code review is the overall design of the CL. Does the interaction between different code segments in CL make sense? Should this change belong to the codebase, or to a package? Does it integrate well with the rest of the system? Is now a good time to introduce this change?
Function
Does this CL serve the developer's purpose? Is the developer's intent good for users of the code? Code "users" can refer to end users (who are affected by code changes) and developers (who will "use" the code in the future).
In most cases, we want developers to test the CLs first to make sure they work correctly. But as a reviewer, you still have to consider edge cases like finding concurrency issues, trying to think like a user, and finding bugs that you can't see just by reading the code.
You can also verify the CL if you wish. If a CL affects the user, such as a UI change, then this is a good time to validate the CL. It's hard to understand how some changes will affect users if you just look at the code. For such a change, if it is not convenient to run it yourself, you can ask the developer to provide a functional demo.
Another important consideration is whether there are concurrency issues in the CL that could lead to deadlocks or race conditions. These kinds of issues are hard to spot just by simply running the code, and usually require someone (developers and reviewers) to think carefully about them to make sure they don't get introduced into the system.
Complexity
Is CL more complex than it actually needs to be? Check CL at every level, down to every line of code, are they too complicated? Is the function too complex? Are the classes complex? "Too complicated" usually means "people who read the code don't understand them quickly", but also "developers may introduce bugs when they call or modify this code".
Over-engineering is a special kind of complexity where developers write code that is more generic than it actually needs to be, or adds functionality that the system doesn't currently need. Reviewers should be wary of over-engineering and encourage developers to only address issues that need to be addressed now, not issues that may need to be addressed in the future. Future problems should be solved after they arise, because then we can see their actual state and needs.
test
Ask developers to do unit testing, integration testing, or end-to-end testing. In general, tests should be included in a CL, unless the CL is only for emergencies.
Make sure that the tests in the CL are correct, reasonable, and useful. Because tests cannot test themselves, and we rarely write tests for tests, we must ensure that tests are valid.
Will the test fail if something goes wrong with the code? Will they falsely report if the code changes? Does every test have an assertion? Are tests categorized by different test methods?
Remember that test code also needs to be maintained.
name
Did the developers use good naming practices? Good naming should adequately convey what an item (variable, class name, etc.) is or is used for, but not so hard to read.
Notes
Are developers writing clear comments in natural language? Are the comments they write required? In general, comments should be used to explain what the code does, not what they do. If the code is not clear enough to explain itself, then it should be simplified. There are of course some exceptions (for example, regular expressions and complex algorithms that would benefit someone reading the code if they could explain what they were doing), but most comments should point out information that is not possible in the code, such as The reasoning behind these codes.
Other annotations that come with CL are also important, such as telling a to-do item that can be removed, or a recommendation not to make code changes, etc.
Note that comments are not the same as class, module, or function documentation. The purpose of documentation is to describe the purpose, usage, and behavior of the code.
code style
Google provides code style guides ( http://google.github.io/styleguide/ ) for major programming languages and most minor programming languages, so make sure CL follows the proper guidelines.
If you want to make improvements to a style not mentioned in the guide, you can prefix the comment with "Nit:" to let the developer know that this is an area you think could be improved, but is not mandatory. But please don't block CL submissions just based on personal preference.
Developers should not put style changes together with other changes, making it difficult to see what has changed in the CL, making merges and rollbacks more complicated. If a developer wants to reformat the whole file, have them make the reformatted file a separate CL and feature changes as another CL.
Documentation
If the CL causes changes in the way users build, test, interact, or release code, make sure that the related documentation is also updated, including the README, g3doc pages, and other generated reference documentation. If CL has removed or deprecated code, consider whether the related documentation should also be removed. If documentation is missing, ask the developer for it.
View every line of code
Look at every line of code. There are things to look at, like data files, generated code, or large data structures, but don't just skim a class, function, or block of code and assume they all work. Obviously, some code needs to be checked carefully, and it's entirely up to you which code, but you should at least understand what the code is doing.
If the code is complex or you struggle to read it quickly, making the review process slow, let the developers know and ask them to clarify before proceeding with further review. If you don't understand the code, chances are other developers won't understand either. Therefore, asking developers to clarify the code is actually helping future developers understand the code better.
If you understand the code but don't feel qualified to do a code review, make sure that a qualified CL reviewer takes security, concurrency, accessibility, internationalization, etc. into consideration when reviewing your code.
context
Code review tools usually only show the code that was modified, but sometimes you need to look at the entire file to make sure the code changes make sense. For example, you may only see four new lines of code added, but if you look at the entire file, you will see that these four lines of code are in a 50+ line method that needs to be split into smaller methods .
You need to think about CL based on the whole system. Does this CL improve the code quality of the system, or does it make the whole system more complex and less predictable? Don't accept CL that degrades the quality of your system's code. Most systems are complicated by the accumulation of many small changes, so try to avoid the complexity of small changes.
Bright side
If you see something nice in CL, let the developers know, especially when they solve the problem in a good way. Code reviews usually only focus on what's wrong, but good code practices should also be encouraged and appreciated. Sometimes it's more valuable to let developers know that they're doing something right than letting them know that they're doing something wrong.
Summarize
When conducting code reviews, you want to make sure that:
- Good code design.
- Features are useful to code users.
- UI changes should be reasonable.
- Parallel programming is safe.
- Code complexity should not be greater than it should be.
- There is no need to implement requirements that may arise in the future.
- There are proper unit tests.
- Well-designed test cases.
- Clear naming is used.
- Clear and useful code comments that explain the "why", not the "what".
- Proper code documentation.
- Code should follow a style guide.
Check every line of code, see the context, make sure you're improving the quality of your code, and give a thumbs up to developers who are doing well.
Check CL
Now that you know what to focus on in a code review, how can you effectively conduct a cross-file code review?
- Does the code change make sense? Are they well described?
- Let’s first look at the most important part of the code change, how is it designed as a whole?
- Check the rest of the CL in the proper order.
Step 1: View code changes holistically
Take a look at the CL description first to see what this CL does. Does it make sense to make this change? If the change is unnecessary, please respond immediately and explain why the change should not have occurred. When you reject such a change, suggest to the developers what they should do.
For example, you could say: "Looks like you're doing a good job at this, thanks! However, we're going to remove this system, so don't want to make any changes to it right now. Maybe you can refactor another class"?
Note that reviewers should be polite when rejecting a CL and suggesting alternatives. Politeness is important because as developers we want to respect each other, even if we disagree.
If there are a lot of CLs that you don't want, consider retooling the development team or external contributors' development process to allow for more communication before new CLs are developed. It's much better to tell people what not to do ahead of time than to throw them away or do a complete rewrite when they're done.
Step 2: Check the main parts of the CL
Find the main file for CL. Usually a CL will have a file that contains the major logical changes, that is, the main part of the CL. Taking a look at these major sections first helps to understand the whole context and speed up code reviews. If the CL is so large that you can't tell which parts are the main ones, ask the developers, or ask them to split the CL into multiple CLs.
If there are serious design issues with the main part of the CL, get back to the developers immediately, even if you haven't had time to check the rest of the CL. Checking the rest of the CL at this point can be a waste of time, because if the main part has serious design problems, the other parts become irrelevant.
Why reply to the developer immediately? There are two reasons:
-
After the developer has issued a CL, the subsequent development work will continue. If the CL you're reviewing has serious design issues, they also need to rewrite subsequent CLs. So, it's best to tell developers before they spend unnecessary time on questionable designs.
-
Large design changes take longer than small ones. In order for developers to be able to commit to the deadline while maintaining the quality of the codebase, get them to start rewriting work as early as possible.
Step 3: Check the rest of the CL in the proper order
After confirming that there are no serious design issues with the overall CL, try to check the other files in some logical order, making sure you don't miss a single file that needs to be checked. Usually, after you've checked out the main files, it's enough to go through each file in the order the code review tool displays them. You can also look at the test code before checking the main code to get a rough idea of the code changes.
speed of code review
Why do code reviews need to be done quickly?
At Google, we optimize for the overall delivery speed of the development team (rather than the speed at which individual developers can write code). Individual development speed is also important, but not as important as the development speed of the entire team.
When code reviews are slow, the following things happen:
-
The overall development speed of the team is reduced. If individual developers are unable to respond quickly to reviews, it may be because they have other things to do. However, if every CL had to wait for review after review, new features and bug fixes from other members would be delayed, possibly days, weeks, or even months.
-
Developers started protesting the code review process. Developers may feel frustrated if reviewers have to reply every few days, but every time they ask for major changes to the CL. Often, they complain that the reviewers are too harsh. If reviewers are able to provide feedback quickly, the complaints go away, even if the changes they asked for were the same. Most complaints about the code review process can actually be resolved by speeding up the review process.
-
Code quality is affected. If the review rate is slow, the pressure on the developers will also increase because they cannot submit less-than-perfect CLs. A slow review process also hinders code cleanup, refactoring, and further improvements to existing CLs.
How fast should code reviews be?
If you're not concentrating on the task at hand, you should review the code in the first place.
It is best to take no more than one business day to respond to a code review.
If these principles are followed, a typical CL can go through multiple rounds of review in a single day (if needed).
speed and interruption
There is a situation where if you're concentrating on the task at hand, like writing code, don't interrupt yourself for a code review. Research shows that it can take a long time for developers to get back to their previous state after being interrupted. So, from a team as a whole, interrupting yourself while writing code is more expensive than having another developer wait for a code review.
So, in this case, you can wait until the work at hand can stop before starting the code review. It could be after finishing the coding task at hand, after lunch, after a meeting, after a break, etc.
Quick response
When we say code review speed, we mean response time, not the time it takes for a CL to complete the entire review process and commit to the codebase. Ideally, the entire review process should also be fast, but the speed of response to a single review request is more important than the speed of the entire process.
It can sometimes take a long time to complete the entire review process, but the quick response of reviewers throughout the process can greatly reduce developer frustration with "slow" reviews.
If you're too busy, start by sending a response to the developers to let them know when you can start a review, or suggest another reviewer who can respond more quickly to review the code, or provide some initial feedback.
The most important thing is that reviewers spend enough time reviewing to ensure that the code conforms to the standard. But in any case, the best response speed is still faster.
Code reviews across time zones
When conducting code reviews across time zones, try to respond while the developer is still in the office. If they've gone home, it's a good idea to make sure they can see that the code review is complete when they get back to the office the next day.
LGTM with annotations
To speed up code reviews, reviewers should give LGTM (Look Good to Me, no problems) or pass for the following two cases, even if they leave open issues in CL:
- The reviewers are confident that the developers will take care of the suggestions and comments given by the reviewers.
- The rest of the changes are minor and not necessarily required to be done by the developer.
When developers and reviewers are in different time zones, it's best to use LGTM with annotations, otherwise developers may have to wait an entire day for "LGTM, approved".
large CL
If someone sends you a big code review and you're not sure if you have enough time to complete the review, it's common practice to ask the developer to split the CL into several smaller CLs. Doing so is generally reasonable and beneficial to reviewers, even if developers need to do a little extra work.
If a CL cannot be split into smaller CLs, and you don't have enough time for a quick review, at least write some notes on the overall design of the CL and send it to the developers. One of the goals of reviewers is to respond quickly to developers without compromising the quality of the code, or to enable them to take further action quickly.
Continuous improvement code review
If you follow these guidelines and are rigorous about the code review process, you'll find that the overall code review process gets faster and faster over time. Developers know what needs to be done to ensure code quality and send you great CL from the start so that reviews take less and less time. Reviewers also learned how to respond quickly. But don't sacrifice code review standards or quality to improve review speed - it won't make anything faster in the long run.
Emergency situations
In some emergencies, CLs have to go through the entire review process very quickly, with a slight relaxation in terms of quality. See these "emergencies" to see which ones meet the emergency criteria and which ones don't.
Review Notes
Overview
- polite.
- Explain your reasons.
- Give clear direction, point out problems, and let developers decide how to make tradeoffs between the two.
- Developers are encouraged to simplify the code, or add code comments, rather than just asking them to explain the intricacies of the code.
polite
In general, courtesy and respect are important. One is to make sure your comments are for code and not for developers. You don't necessarily have to do it all the time, but it's definitely necessary when you want to say something that might be exciting or controversial to the developer. E.g:
Bad saying: "why are you using threads in this place, obviously you won't gain any benefit".
Good saying: "Using a concurrency model here adds complexity to the system, but I don't see any real performance benefit, so this code is better off using single threading, not multithreading".
explain the reasons
As you can see from the positive examples above, this helps developers understand why you are making these recommendations. You don't always have to provide this information in reviews, but it would be nice if you could give more explanation of your intent, the best practices you followed, or how your suggestions would improve code quality.
give guidance
In general, fixing CLs is the responsibility of the developers, not the reviewers. You don't need to provide developers with detailed solutions or write code for them.
That doesn't mean that reviewers shouldn't help developers, though. You'd better be able to make a trade-off between pointing out the problem and giving guidance. Pointing out problems and letting developers make decisions helps developers learn and makes code reviews easier. It also produces better solutions because developers know the code better than reviewers.
However, sometimes it is more useful to give instructions, advice, or code directly. The main purpose of code review is to get the best possible CL. The second purpose is to improve the skills of developers so that fewer reviews will be needed later.
accept annotations
If you ask a developer to explain a piece of code you don't understand, they'll usually go and rewrite the code and make it clearer. It's also sometimes appropriate to add comments to code, as long as it's not just used to explain overly complex code.
Don't just write comments in a code review tool, because it won't help people who are going to read the code in the future. There are only a few cases where this is acceptable, e.g. you're not very familiar with the review stuff and the developer's explanation is well known to many people.
Code review pushback
Sometimes, developers push back code reviews. They may disagree with you, or they may complain that you are too strict.
who is right?
If the developers disagree with you, take a moment to think about whether they are right. Usually, they are more familiar with the code than you, so probably know some aspects of the code better. Do their arguments make sense? Does their pushback make sense from a code quality perspective? If yes, let them know they are right and the problem is solved.
However, developers are not always right. In this case, the reviewers further explain why their recommendation is correct.
If reviewers feel that their suggestions can improve code quality, and feel that the code quality improvements that the review brings are worth the extra work of developers, then they should stick to it. Improving code quality often consists of a series of small steps.
Sometimes you need to spend a lot of time explaining things over and over again, but always be polite and let the developers know you know what they're talking about.
Excited Developer
Sometimes reviewers feel that developers will be upset if they insist on making changes. Developers do get frustrated sometimes, but it's usually short-lived, and then they thank you for helping them improve the quality of their code. If you're being polite during the review process, the developer won't be upset at all, and that worry may be superfluous. Often, it's the way you write annotations that upsets developers, not your insistence on code quality.
solve it later
A common reason for pushback is that developers want to get things done as quickly as possible. They don't want to go through round after round of code reviews, they say they'll fix legacy issues in subsequent CLs, you just let the CL pass now. Some developers will do well enough to develop subsequent CLs as soon as they are submitted. But experience has shown that the longer developers work on the original CL, the less likely they are to make subsequent fixes. Unless the developer fixes it immediately after submitting the CL, it usually doesn't do it again after it's passed. This is not because the developers are irresponsible, but because they have a lot of work to do and fixes are often forgotten. So, it's best to ask the developers to fix the CL right away.
If a CL introduces new complexity, it must be cleaned up before committing, except in emergencies. If the CL exposes something that cannot be fixed at the moment, the developer needs to document the bug and assign it to himself so it doesn't get missed. They can also add TODO comments to their code, pointing to bugs that have already been logged.
Complaining that the judging is too strict
If your previous code review was relaxed and then suddenly strict, it may cause some developers to complain. But that's okay, speeding up code reviews often makes those complaints fade away.
Sometimes these complaints can take months to clear up, but developers usually see the value in code reviews at the end of the day because they see that rigorous code reviews can lead to great code. Sometimes the person who protests the loudest can even become your most staunch supporter.
conflict resolution
If you've followed the above and still encounter conflicts that you can't resolve during the review process, please refer to Code Review Standards again for guidelines that can help resolve conflicts.
Original link: https://google.github.io/eng-practices/review/reviewer/