Posted by There are two major schools of thought when it comes to how best to perform a code review. The first and simplest strategy is to sit down with a colleague, go through the code together, and discuss the finer points of programming. The other, less interactive way, is to use one of many tools available on the market to facilitate the discussion. But what is the best way to maximize value, improve the development skills of your team and promote collaboration? As with most things, the answer is usually somewhere in the middle.
In-person reviews
Let’s start by looking at in-person code reviews. According to a study done by Forrester Consulting, it’s still the predominant way of going about doing a code review. A big reason why it’s so popular is because of its simplicity: you only need to have someone slide their chair over to your desk and start looking at the code you just wrote!
Top 3 reasons for using in-person reviews
- You’re looking to bring code review to your organization for the first time. The KISS principle serves you well here. You’ll quickly see the benefits of reviewing each other’s work without too much up-front investment.
- Your team is mostly co-located, making it easy to pair up at someone’s desk to review code.
- You want to promote a culture of openness and sharing and prefer talking to using sometimes cold feeling tools
There are some inherent problems with doing in-person code reviews as it pertains to code quality, however. For starters, there’s no way to track metrics on the improved quality of the code. It’s also hard to tell how much of the codebase is actually being reviewed as it depends greatly on the reviewee deciding what parts to focus on during the review. This can easily lead to parts of the code being missed or forgotten.
A final caution with regards to code quality; an in-person process makes it more difficult to identify which defects were addressed and which ones weren’t, defeating the purpose of reviewing it in the first place.
There are also interpersonal and communication issues that can arise and spell disaster with in-person reviews. When putting a code review process in place, it’s important to often re-iterate that the code review is a learning process, and the goal is not to beat down on a developer. Since it can be confronting to be told that some parts of our code aren’t right, it could be worthwhile to invest in some training on proper communication so that the developers can find ways of suggesting changes without offending each other. The communication problem gets bigger – and more important to address – when people are separated by distance, culture and language.
In terms of cost to the organization, it may be slightly more expensive to run in-person reviews when compared to tool-based review. Assume a 2-person, 30-minute meeting to review the code. You’ll be “losing” an hour’s worth of development time since both reviewer and reviewee are completely engaged for that time. It may take more time to apply fixes to defects as well. In terms of return on investment, you should see a reduction in the number of defects found once the code is pushed out, a more maintainable code base in the long-run, and a better distribution of knowledge of the application within the team. Overall, these benefits clearly outweigh their associated costs.
Tool-based review
Let’s look at the other side of the coin and see if it’s worth investing in a tool to help improve your code reviews. There are many code review tools out there, with some of the most popular being Atlassian Crucible, Facebook Phabricator Differential, and Google Gerrit. These tools all have different features and are best geared towards specific applications and source control systems, but their core functionality remains the same and will be treated equally for the purposes of this article.
Top 3 reasons to implement a tool-based code review:
- You want the code review process to be integrated to your development workflow. This ensures that reviews get done on time, no code or review ever gets forgotten, and it becomes a habit for your team without seeming like a burden.
- You want quantifiable proof that code reviews are giving you a good return on investment. There are numerous metrics that can be calculated, the most popular being defect rate, defect density and inspection rate. These will give you insights as to the real ROI of code reviews.
- Your team is separated geographically. The tool will help facilitate discussion and provide a central place where the whole team can go to keep track of code under review.
Another tangible reason to opt for a tool-based review is to give more freedom to the reviewers to perform the review at their discretion. Context-switching is very costly in programming, and providing a window of time in which developers can complete the review will go a long way to reduce those switches. You do want to make sure you have an expiry time on the review otherwise you may end up with reviews pilling up in your tool, which could lead to the code review process coming to a screeching halt.
The biggest downside to tool-based review is, of course, the cost of the tool. Not only might the tool have licensing requirements that can become expensive as your team grows, but you’ll also need to invest in time to ensure that the developers know how to use the tool correctly.
Another significant drawback can also present itself when it comes to interpreting the comments that were left within the review. Often times, a message can be misunderstood, or interpreted as being passive-aggressive. The team should be given resources and suggestions on how to best word comments to avoid potential conflict with their colleagues.
As a related side-note, you should also look to include some kind of automated quality analysis in the build process. This prevents code reviews from degenerating into formatting, naming, and preferred syntax tangents and allows developers to focus on the core functionality that was implemented.
The hybrid solution
The final solution we’re going to look at – hybrid code reviews – are my personal favorite. It combines a lot of the advantages of the first two, and somewhat reduces the risks associated with the previously discussed techniques.
What the process looks like:
- The reviewee prepares the code review in the tool of choice of the team and sends it to one or two peers, with an expiry date and time.
- The reviewers choose when to inspect the code, before the expiry time, and comment as appropriate within the tool.
- Either in person or via video conference, the reviewers go over the comments with the reviewee, and together decide which items should be addressed.
- The comments that aren’t to be addressed are deleted from the review. Only issues that will be resolved are left as part of the review.
The main advantage to this technique is that any missing information from the comment can be contextualized and explained in the third step. This will reduce the chance of misunderstandings and frustration, which can occur easily when using a tool-based or in-person review process only.
It also avoids long comment chains in the tool. Those long comment chains (often done via email notifications) can result in lots of context switching and even further reduced productivity. For that reason, it’s important to disable email notifications in the tool for the process to work as effectively as possible.
You’ll also get the metrics that only the tool can provide you, giving you insight into the true return on investment that code review can bring to your team.
As a parting note…
Regardless of the approach you choose to use, it’s important to note that *any* form of code review is better than no review process at all. If you’re just starting to experiment with code review, as with most things in development, your goal should be to keep it simple and strive to continually improve your process as the team grows together.
Marc Roussy 