In my more than 10 years of professional software development experience, coffee and code reviews have been the two constants. For a practice that is so ubiquitous in the industry it is surprising how misunderstood it is, even in teams with experienced developers. I have rarely seen teams critically examine the review process, discuss on why and how to be effective at it. Unfortunately, it is not uncommon for many to think of it as a bureaucratic part of the development process.

Let's begin by stating the obvious, all code must be reviewed and approved by a team member before it is pushed. Code review without a doubt is an essential part of the software development process, that makes it all the more important that teams should practice it with the right intent. An in-effective code review process can lead to:

• Reduced productivity of the team.
• Increased developer frustration.
• Toxic culture in the team.

The intention of this post is to (1) discuss the goals of code review (2) provide recommendation how to approach code reviews as authors and reviewers.

Why bother with Code Reviews?

As a developer you will be spending a large chunk of your time either reviewing code or getting your code reviewed. In order to make this process effective you should be clear on the primary reasons for doing Code Reviews. Lack of clarity on this is often the reason for the code review process to go awry in the team.

👨‍🏫Knowledge Transfer

This in my opinion is the most important reason for code reviews. They ensure at-least one person apart from the author is aware of the change being pushed. It allows you to socialise your code change among your team members enabling you to reduce the bus factor.

What is the Bus factor? Simply put, the bus factor corresponds to the number of people in your team that can get hit by a bus before your project/product/system/whatever is in grave danger/stuck/blocked/doomed. The lower the number, the higher the risks.

🧙‍♂️Mentoring opportunity

Code reviews are an excellent way to create an environment of mutual mentoring. Over the years peers reviewing my code has been a major source of learning for me. It remains my preferred choice for helping new developers improve their code quality. No formal mentoring or training program is required, just comments on how to improve the code serve as a source for learning for everyone in the team.

💁‍♀️Improving code quality

This is an obvious one. The aesthetics of the code are just as important as its functional correctness. Code reviews play a key role in ensuring best practices are followed, design principles are adhered to, code is readable and obvious etc. Every developer in the team is kept accountable for maintaining the high coding bar. It also helps with maintain consistency in the code.

🫂Build culture

This one of the long term benefits of code reviews. It is one of the common ways developers in a team interact with each other, hence code reviews go a long way in a building a healthy and collaborative culture in the team. A healthy code review culture can help developers in the team learn how to better communicate complex, abstract concepts to each other. Resolve disagreement/conflicts which are bound to occur as there are multiple ways to achieve the same thing through code. Code reviews also present an opportunity for senior devs in the team to encourage newer members to express their opinions.

🐞Catch Bugs

Finally, code reviews can also help with reducing bugs. More eyes on the code does help with catching logic errors or edge cases. However unit tests, integration test, local dev testing and static code analysis tools are much more effective at ironing out bugs. As an author of a diff it is your responsibility to ensure the correctness of your code, you should never rely on code reviews for detecting errors.

Recommendations

Now that we have established what are the goals of the code review process, below are some recommendations on how to approach code reviews so we can take achieve said goals.

Authors

Have empathy for the reviewers of your code. They are taking time out to review your code and unblock you. Attempt to minimise the amount of work a reviewer has to to do to review your code.

• Clearly setup the context in the CR description. Anyone in the team should be able to read the description know what the code change does.
• Test for correctness before raising the CR and mention details of the testing done.

• Emphasise on the readability of your code. For inevitable complexity that can creep in add comments describing what and why.

• Address all comments received before raising a new revision. Always double check to ensure you haven't missed anything. If you are not taking the recommendation of the reviewer call that out.

• Review your code change yourself before publishing it. This is the most common advice I give to engineers who want to reduce the number of revisions their reviews goes through. Wear the code reviewers hat and review it as you would review someone else's code before you hit the publish button.

• Keep the CR length short. 1-2 pages are ideal, anything beyond 3 pages is too long. Quality of the code reviews goes down exponentially as the number of pages of review increases. It also increases the chances of more iteration as the reviewer might discover something new they missed in the previous version. Also no one likes reviewing thousands of line of code in one go.

• You are not your code. Try not to take the code review comments personally (easier said than done). Think of review comments are an opportunity to improve your code, learn something new. Don't get discouraged by them.

• Defend the design choices you have made in the code, if you have thought about it let the reviewer know about your reasoning. It is likely the person reviewing your code has not thought about it as deeply as you have. However avoid debating in the comments, always quicker to switch to real-time communications to resolve debates.

Reviewers

Empathy flows both ways, just like the author reviews should also begin with empathy. Work towards un-blocking the author.

• Don't overwhelm the author of the code with too many comments. If there are too many issues with the code connect with them directly.
• Keep your comments objective, avoid any sarcasm or emotive language. Comment on the code not the author.

• Review comments aren't just for being critical of the code. If you notice high quality code or an improvement in the code quality of an engineer use it an opportunity for appreciation and recognition. This creates a positive feedback loop and encourages people to write better quality code.

• Recognise the fact that reviewing code takes time, make sure everyone including your manger understands that. Don't rush the reviews, ensure the entire code change is reviewed before publishing your comments. Review the unit tests to ensure functionality tests are in place.

• Try to limit the number of revisions 2-3. Two many revisions are a time sink for both the author and reviewer, leads to churn and in general slows down the team. Defer to real-time connects to resolve the issues.

• Distinguish between facts and opinion. In case of the later clearly state that and explain the reason for your preference. Pointers to stack overflow or blog posts can be very helpful here.

• Ship the code if all your comments are non-blocking/minor to unblock the author. This will build a culture of trust in the team. High trust teams are more efficient. Having said that do check that the comments are addressed, talk to the author if that is not done.

• Code review is not the right place for questioning the architectural choice, if this happens it's a failure of the design review process.

• Try to keep the general tone of comments light and fun. Using meme's and ascii art help with that.

• Encourage everyone to participate in the review process. It should not be relegated to senior engineers in the team.

Conclusion

Teams should have a clear understanding of the goals of code review process, they serve as guiding first principle and will help them maintain the effectiveness of the process. Having a common document capturing the goals and recommendations is also a good idea as the team evolves over time.

Thanks for reading!