Code reviews: whys and hows

Code reviews are a great way to get feedback going in the team while sharing knowledge. As any other practices it’s important to understand the principles behind it so that they can be adapted to the context at hand to achieve team’s goals.

Why

As already said, code reviews enable giving and getting feedback about some specific code. In fact, they can be employed to improve code quality. The choice of a generic term such as “code quality” is intentional: the team decides how to fine tune code reviews.

Also, being either on the author or reviewer side encourages sharing knowledge. In other words, the team increases the bus factor and facilitates introducing people to unknown part of the system. Furthermore, they enable learning via the “I didn’t know you could do that” moments.

As a rule of thumb, it’s a good idea to discuss higher level concerns before opening the editor and writing code to avoid wasting days of work. But some other times discussions are better done with code in front of our eyes: code reviews represent one way of doing it offline.

Lastly, code reviews make you write oral history down. In the case of Git, for example, besides checking single commits it’s possible to check the pull request that contained that commit. This is incredibly helpful when trying to make sense of some software.

How

The points above are the reasons why I keep code reviews ready in my toolbox. But theory is nothing without practice, so here’s some tips.

As an author
- Do a self review before asking others.
- Keep pull request small (~200 lines of code).
- Provide context. Writing software means learning about both business and code: make sure that knowledge is available to reviewers (consider pull requests template)
- Keep commits small and meaningful.
- Try hard not to get defensive when reading comments.
- Always assume the best intentions of the other person.
- Be grateful for code reviews.

As a reviewer
- Timebox code reviews: set a timer and just stop whenever time’s out. This really depends on the context but I’d suggest starting with 10 minutes. Most of the times when you need more than that there’s something you can improve in the process.
- Code review once a day not to keep other people blocked.
- Praise good work.
- Ask questions, do not dictate. Nobody likes to read stuff like “why didn’t you just …?”. Rephrase to “what do you think about…?”, “did you consider…?”, “can you clarify…?”. Besides being more respectful it fosters conversation, which is exactly what we are looking for.

As a team
- Automate as much as possible (eg linters).
- Consider having multiple reviewers to exploit each person’s expertise. But not too many because this has diminishing returns.
- Keep comments small. If you need to write a lot just talk face to face to avoid endless ping pongs.
- Code reviews are just a point of view: treat them as opinions and agree to disagree.

Credits

This post is a collage of ideas stolen from other people. They make a better job than me at explaining this stuff, so please be sure the check them out.

In particular, if you are looking for scientific proof be sure to watch “Effective Code Review” by Dougal Matthews.

Some studies cited there are:
- “the average defect detection rate is only 25% for unit testing, 35% for function testing and 45% for integration testing. In contrast, the average effectiveness of design and code inspections are 55% and 60%“ (Code Complete by Steve McConnel)
- “Formal design and code inspections […] often top 85% in defect removal efficiency and average about 65%” (Measuring defect potentials and defect removal efficiency)
- “While finding defects remains the main motivation for review, reviews are less about defects than expected and instead provide additional benefits such as knowledge transfer, increased team awareness, and creation of alternative solutions to problems.” (Expectations, outcomes, and challenges of modern code reviews)
- “larger patches lead to a higher likelihood of reviewers missing some bugs”

To which I’m adding this other study:
- An hour of inspection saves 33 hours of maintenance

Also, here are two other great talks:
- How to stop wasting your time and start performing useful code reviews by Maria Khalusova
- RailsConf 2015 — Implementing a Strong Code-Review Culture

And a huge thanks goes out to the Software Craft Communities out there. If you are up to inspiring chats please head there and join Slack or your local community.

Get the latest content via email from me personally. Reply with your thoughts. Let’s learn from each other. Subscribe to my PinkLetter!