We mainly use two code review formats in our projects: collective review which is rather formal and peer review, which is lighter. Both have advantages and drawbacks: Let’s look into these formats together and see how to implement them within a team.
But first things first: what is a code review and what benefits can we expect?
In most areas involving writing, we cannot imagine that what is written is issued without proofreading. An article will always be proofread before publication (e.g. the one you are currently reading), either to check the substance – is the subject of the article well treated? – or the form – spelling, grammar, structure and text readability. Similarly, the code review practice consists in having one’s code read again in order to track as many defects as possible, be it on the content – does this code work, and correctly implement the required feature? – or the style – clarity, readability, standards compliance, etc.
What about you: how many lines of code have you ever deployed in production without proofreading?
Code review is a practice almost as old as software development and widespread among companies like Microsoft or Google. There is a good reason for this: it allows defect detection earlier in the development process, yet the practice is relatively uncommon in the teams we meet. Sometimes this is because it is unknown, but it’s more usually for the wrong reasons: “We have no time, it’s too expensive” or “We tried but it turned into a troll discussion” or even “I do not want to, it’s just policing!”. We realize that it’s not a practice that simple to set up!
Detect defects as early as possible
The main objective of a code review is the same as other insurance methods of software quality: find code defects as soon as possible. The benefits of code review are well established: according to studies compiled by Capers Jones on more than 12,000 projects, collective code review helps to detect about 65% of the defects, 50% for the review by a peer, while tests detect only 30% of the defects on average.
Note that we do not say you should give up other quality assurance practices: it is an essential practice to combine with other practices, such as testing, to maximize the product quality before making it available to users. There are other benefits to code review:
- Improve intrinsic software quality and develop standards
- Collective code ownership: having the code being read by someone other than its author helps reinforce the collective code ownership, and reduce the risk of excessive specialization, when only the author of the code is able to change it
- Learning: code review is a way to train younger developers while sharing standards, showing them some techniques, or how some features are implemented. It’s also an opportunity for those who arrived more recently to bring a different perspective and propose new approaches
- Improve the quality of exchanges between developers.
All these points highlight code review as an indispensable collective practice that contributes to spreading a culture of quality within the team.
Collective code review
Collective code review consists in organizing formal inspection sessions, regular and within a group, dedicated to the detection of defects.
We suggest the following mode:
How to select the right code?
In order to detect new defects, we often select the code related to the latest features.
- Ideally, we should read all the code recently produced, but it is only feasible if the team is small enough
- Otherwise, we select in the recently modified code a sensitive or complex part, or one that introduces new concepts, new piece of software architecture, etc.
You can also select existing code that “scares”, that is complex or that generates frequent regressions, for example if you know you will have to make it evolve soon.
Peer code review
The peer review consists in adding a step in the development process. This is a more widespread practice because it’s simpler and less burdensome to implement. There are several variations of this type of review, from pair programming to a format close to the collective review, except that the review is made by only one other developer.
Here is a format that we successfully used on several projects:
Who does the code review?
Ideally, the first available person handles the review. As in the collective version, it shouldn’t always be the same person who handles reviews, to promote collective code ownership.
This is a mandatory step in your development process, display it as a new column to your board before the functional review stage.
What to do with defects identified during the review?
To be effective, a code review should be dedicated to address the defects, and corrections or any discussions should be held separately:
- When the correction to be applied is clear and unanimous (functional defect, deviation from an established standard), the author of the code implements the correction after the review and a follow-up is planned to ensure that the defects have been corrected.
- Two implementation approaches can often be argued. In a pair review, involving a third party or the whole team will facilitate decision making.
- When the point of attention is a non-established standard, the team’s written standards must be updated, ensuring that they are shared by everyone.
It is common that some complex issues require an exchange with the entire team:
- You can book an extra half an hour after the collective review or solicit the team for a dedicated point when you are in peer review
- On several projects, we also ritualized a timeframe of one or two hours at the end of a sprint, known as “The Tech Hour” or Dojo, in which we can address these points
Collective or peer review?
The table below gives a (non-exhaustive) list of comparison criteria between the two types of code review:
|Collective review||Pair review|
|Efficiency (number of defects detected)||+++||++|
|Collective Code Ownership and learning curve||+++||++|
|Quality improvement, standards evolution||+++||+++|
The various studies mentioned in Best Kept Secrets of Peer Code Review and the chapters on software quality and collaborative construction practices in Code Complete show that collective review is generally more efficient than peer review, but has the disadvantage of being more difficult and expensive to implement.
These studies also show that the vast majority of defects are identified during the review preparation. This comforts us in the effectiveness of the peer review, provided it is well prepared: it provides a good compromise, avoiding the cost of a meeting with many participants.
You can also use formal collective code reviews in addition to pair reviews:
- in short format, limited to the items which are not obvious and/or not covered by the standards
- for some algorithms or complex designs
- during the initial period of reviews setup, so the team will collectively learn to practice reviews
There are so many blog titles labelled like “The [benefits | dangers] of [Code | Pair Review | Pair Programming]”, but in the end, the debate is elsewhere. Even if we issue an opinion in favor of a preferred format, it does not matter if you do pair programming, collective or peer review: the key is to find the approach that matches the culture of your team.
This article offers an interesting analysis on the subject and we’ll sum up its conclusion as follows: analyze and admit your weaknesses in your collaborative development practices. If you have not yet chosen an approach, exchange with developers who regularly use these practices. Experiment and try to improve, during a retrospective for example.
We have so far described code review formats: through a following article, we will share with you the pitfalls encountered that could put at risk this practice.