The What, Why and How of Code Reviews

Code Collaboration!

This article starts with an outline of the key findings made by the paper “Modern Code Review: A Case Study at Google” by Caitlin Sadowski, Emma Söderberg, Luke Church, Michal Sipko (Google) and Alberto Bacchelli (University of Zurich). You can read the paper here.

I then offer my own interpretation and recommendations based on my experience with code reviews at Disruptive Angels (startup), Twitter and Google as an intern.

Purpose of a code review: force developers to write code that other developers can understand. For Google, the introduction of the code review marked the change from an experimental codebase to one where it’s critical to think about stability and long stable builds, which needed more than one person to understand and work on the same part of the codebase.

Characteristics of a code review

• Informal
• Tool-based: usually using software like Gerrit or platforms like GitHub to assist review.
• Asynchronous: development process is not completely stopped by review
• Focused on code changes: changes to existing code is the main use case.

Background

Google has a trend for reviews with one or two reviewers at most, quick iterations, small changes, and a tight integration with the code review tool. More than 25,000 developers are making more than 20,000 source code changes each workday, in dozens of offices around the world.

Benefits of a code review

• Understandability as someone else, who doesn’t code or think the same way as you do needs to be able to understand what is it that you’re implementing and why.
• Maintainability because the reviewer will have the experience from previous work to determine if your change will enable the software to keep working and able to grow.
• Code style
• Ensuring exhaustive testing, as validating and executing these tests is a tangible evidence that what you implemented aims to not have any bugs.
• Improved security
• Future auditing of changes (tracking): for further work and tracking of a feature, code reviews allow us to keep track of this historical information to have as much context as possible.

Key findings by the author:

1. Defect finding is welcome but it is not the main focus, as the benefits listed above are a higher priority at Google.
2. Code review comments depend on the relationship between the author and the reviewer.
3. Ownership: for each directory of code at Google there’s an owner which must approve the modification.
4. Over 80% of all changes involve at most one iteration of resolving comments.
5. Google’s tools have “Suggested Reviewers” and automatic style checks, which allows nits (nit picky details mostly related to style) to be addressed before the formal review.
6. Most code changes in Google are small, which allow feedback for these changes to be sent in a matter of hours since the time needed for review is small as well. This makes having only one reviewer possible.
7. Expectations for design and rationale behind the code change can lead to delay if not communicated effectively.
8. Google reviewers spend 3 hours reviewing weekly.

Based on my understanding of the key findings and my experience in both startups and big tech companies, here are the key practices and recommendations that if followed can lead to be an agile, iterative and seamless code review:

1. Onboarding is necessary before adding a reviewer to your change. This prevents the relationship between author and reviewer to be a hindrance during the review.
2. Keep code changes as small as possible. If your reviewer addresses small code reviews, they will need less time and research to figure out if your code makes sense. For large projects, it’s a better strategy to break it down to independent components and send them progressively building on top of each other.
3. Aim your code changes to just have one iteration of feedback. To be able to achieve this your code needs to be educational and readable enough to present all the caveats and decisions that the reviewer needs to address in the review, rather than finding in another review feedback round later.
4. This is a collaborative process between the reviewer and reviewee.
5. In my experience, at the start of the project, it’s always a good idea to have a meeting with the potential reviewers and owners of your change before starting to code.
6. Having a document outlining the key design decisions and context and appending it to your code reviews can make it so much better for reviewers to understand the bigger picture, and the description of your code change specifies what this particular change is doing.
7. Make a list of the previously existing code reviews and add them to your code review’s description or other places you can put them in, as history and tracking is very helpful for reviewers as well.

For someone new to software engineering, code reviews might feel unnecessary if you’re not working in a huge tech company. However, with the change of OSS projects from mailing list code reviews to online asynchronous reviews, developers can now experience this regardless.

Today, you can have code reviews simply by making pull requests on GitHub, which allows the features of an asynchronous code review.

In conclusion, code reviews are a tool-assisted, collaborative method of ensuring security, maintainability and readability of your code. For this method to be effective, both reviewer and reviewee need to make sure the conversation between them is agile and iterative. Google achieves this by making reviews small, having comment threads as concise and short as possible, suggesting reviewers for the code and performing automatic style checks on the code to be reviewed. Pair programming and code collaboration are highly valued practices in software development companies like Google, Facebook and Twitter. By keeping the recommendations mentioned in this article in mind when involving yourself in your own code reviews demonstrate communication and collaboration skills in the industry.