13 Code Review Standards Inspired by Google
How to excel at code reviews
In this article, we will briefly go through 13 code review standards that could dramatically help improve the health of your software as well as keep your developers happy.
As the name suggests, code review is a process where one or more developers review or screen the code written by another developer (the author) to ensure that:
- the code does not have any mistakes, and there are no bugs or issues
- it meets all the quality and styling guide requirements and standards
- the code does what it is intended to do
- when merged, it will leave the health of the codebase in a better state
This is why code review is a critical part of software development. The code reviewer is acting as the gatekeeper who decides whether the code is in a state to be part of the codebase and reach production.
Google is known for its technological excellence, and they have effective code review standards that seem to highlight some vital points to keep in mind when reviewing code. At Google,
“The primary purpose of code review is to make sure that the overall code health of Google’s code base is improving over time.” — Google’s Engineering Practices documentation
Here is a list of things to keep in mind when you are reviewing a change list (pull request).
Code Review Standards
1. The code improves the overall health of the system
Every change list (pull request) improves the overall health of the system. The idea is that as a result of such small improvements, the health of the software or codebase will improve after every merge.
2. Quick code reviews, responses, and feedback
First and foremost, do not delay pushing (merging) better code. Don’t expect the code to be perfect. If it’s in a condition that improves the overall health of the system, then ship it.
“A key point here is that there is no such thing as ‘perfect’ code — there is only better code.”— Google’s Engineering Practices documentation
If you are not in the middle of a focused task, then do the code review shortly after it comes; however, one business day is the maximum time it should take to respond to a pull request (change list). It is expected for a change list (pull request) to get multiple rounds of partial/full code review in a single day.
3. Educate and inspire during the code review
Provide mentorship during code reviews by sharing knowledge and experience wherever possible.
4. Follow the standards when reviewing code
Always keep in mind that the style guide, coding standards, and such documents are the absolute authority during code reviews. For example, to enforce consistency between tabs vs. spaces, you can reference the coding conventions.
If Java is your language of choice, then you might find the following article useful that provides a summary of Java coding best practices at giant tech companies useful: “A Short Summary of Java Coding Best Practices.”
5. Resolving code review conflicts
Resolve conflicts by following the agreed-upon best practices in the style guide and coding standards documents as well as seeking the advice and suggestion of others who have more knowledge and experience in the area of the product.
If your review comments are optional or minor, then clarify that in your review comments and leave it to the author to decide whether to address or ignore them.
As a code reviewer, you can at least suggest that the change list (pull request) remain consistent with the rest of the codebase in the absence of a style guide or coding standards.
6. Demo UI changes as a part of code review
If the change list (pull request) changes the user interface, then in addition to the code review, it’s necessary to have a demo to ensure that visually everything looks as expected and matches the mocks.
For the front-end change list (pull requests), it’s always recommended to do a demo/walkthrough or make sure that the change list also includes the necessary UI automation tests that verify the functionality added/updated.
7. Ensure that the code review accompanies all tests
Unless it’s an emergency, the pull request (change list) should accompany all the necessary tests, i.e., unit, integration, end-to-end, etc.
An emergency could be a bug or security flaw that needs to be fixed as soon as possible, and tests can be added later. In cases like this, make sure that appropriate tickets/issues are created and that somebody has taken ownership to get it done right after the hot -fixing or deployment is done.
There is no reason good enough to skip the tests. If due to time constraints, some of the goals are at risk of not being delivered, then the solution is not to skip tests but to descope the deliverables.
8. When focused, do not interrupt yourself to do code review
If you are in the middle of a focused task, don’t interrupt yourself, as it might take a long time to get back on track. In other words, the cost of interrupting a focused developer is more than making a developer wait for a code review. Do the code review after your planned breaks, i.e., lunch, coffee, etc.
The expectation is not always to get the entire code review process done and merged on the same day. What matters is to give the author some feedback quickly. For example, you might not be able to do a complete review, but you could quickly point out a few things that could be looked into. This would significantly help reduce frustrations during code reviews.
9. Review everything, and don’t make any assumptions
Look at every line of code that is being assigned to you to review. Don’t make any assumptions about human-written classes and methods, and you should make sure that you understand what the code is doing.
Make sure to understand the code that you are reviewing. If you don’t, then clarify it or ask for a code walkthrough/explanation. If there is a part of code that you are not qualified to review, then make sure that there are other qualified developers who could review those parts of the code.
10. Review the code with the bigger picture in mind
It’s often helpful to look at the changes from a broader context. For example, a file was changed, and four (4) lines of code were added. Don’t only review the four (4) lines of code; instead, consider reviewing the entire file and check the new additions. Do they degrade the quality of existing code, or do they make the existing function a candidate for refactoring?
If such simple additions are reviewed not within the context of the function/method or class, then over time, you will inherit a class that is unmaintainable, super tangled, not easy to test, does everything, and is hard to extend or refactor.
Remember, just as little improvements over time add up and result in a great product with the least number of defects, similarly, slight code degradations or tech debts over time will compound and result in a product that’s challenging to maintain and extend.
11. Recognize and encourage good work during code review
If you see something good in the change list, don’t forget to shout out the author for good work and encourage them. This is something that I have personally not done before. The aim of the code review should not only be to find mistakes but also to encourage and mentor developers for the great work they do.
12. Be mindful, respectful, kind, and clear in your code review
It’s crucial that during the code review, you are kind, clear, courteous, and respectful while also being very clear and helpful to the author. When reviewing the code, make sure to make the review comment about the code and not the developer.
Here is a guide by Google on how to be respectful during the code review: “Respectful code Reviews: A Guide for Code Reviewers.”
13. Explain your code review comments and keep scope in mind
Whenever the code review comment suggests an alternative approach or flags something up, it’s crucial to explain why and provide an example based on your knowledge and experience, to help the developer understand how your suggestion is going to help improve the quality of the code.
When suggesting fixes or changes, find the right balance on how to guide the author to fix the code. For example, I appreciate guidance, explanation, and some tips or suggestions, and never the entire solution.
For a more in-depth dive into Google’s code review standards, please check out the link below
How to do a code review
The pages in this section contain recommendations on the best way to do code reviews, based on long experience. All…
The cost of interrupting a focused developer is too high compared to making a developer wait for you to review their code in your next available time slot. For more on that, check out
The Cost of Interruption for Software Developers — bright developers
Everyone that works in an office (especially in an open office space) will have to deal with daily distractions, and…
Alex Hill touches on some really helpful topics on how to give and receive code review feedback in “The Art of Giving and Receiving Code Reviews (Gracefully).”
Further on code review, Michael touches on some fundamental aspects of what makes an effective and better code review.
Thank you for reading, and I hope that you have enjoyed this article. If you have any comments or suggestions, please feel free to share them with the rest of us in the comments section.
Stay tuned for future articles on similar topics.