Let me start by being honest. I have not done a lot of code reviews, and I have not had my code reviewed by others a lot. Truth be told, in the last two decades (since 1999) that I have been programming, I have not worked in an organisation where code reviews were part of the regular process of doing things.
However, from time to time, I have worked in some teams with a regular code review practice, especially in the last decade.
This article is me sharing my thoughts on code reviews from that perspective – the perspective of someone who has not had a lot of experience with code reviews, perhaps even secretly hated it, and only come to love code reviews and appreciate its value in the last 5 years or so.
Code Reviews Are An Investment
Over my career I have worked with business leaders developing products in our ever changing industry where time is always scarce. Early on in my career, I believed code reviews were just a waste of time, or just geeky stuff without any real business value.
However, today I see code reviews as an investment – into the kind of company and culture you want to build, the kind of people you want to attract, and the kind of problems you want your people to be working on.
So What Changed?
Albert Einstein once said something which I believe to be true for most good things in life – Not Everything That Counts Can Be Counted, And Not Everything That Can Be Counted Counts. Early on in my career, I made the mistake of looking at code reviews from the lens of “What is the immediate value?”
Back then I only saw code reviews as an extra step in the process to ship products, which was and remains my top priority. However, after having worked with a few teams where code reviews was the norm, I realised that code reviews can be a secret superpower for your product, business and organisation.
Set The Right Context
To the unexperienced eye, code reviews might still look like an extra step in the process without any immediate value. This is especially true for product and tech leaders (like it was for me) who have not experienced working in an environment where code reviews was a norm.
It is therefore very important to set the right context – of seeing them as an investment – for your team members, for your business leaders, and especially for new people joining your company so that everyone understands its importance long term value.
Specific Tips on How To Do Code Reviews Better
It is so easy to do code reviews wrong, especially if people (developers and business leaders alike) have resistance to the process. By setting the right context (of investment) you can create a forward looking organisation to continuously improve the process of code reviews.
This makes sure you get the most of its value. Here are few specific tips on how you can do so :-
- Make people feel safe. It is easy for people not used to code reviews to feel intimidated, especially in the presence of experienced developers. Share examples of what code reviews are, and what they are not to calm nerves and create a safe environment.
- It helps to have company wide engineering / coding guidelines to fall back to. Set in stone what is acceptable / not acceptable.
- Balance out the positive and negative feedback. Code reviews are not only for critical feedback. If you find a good example of doing something the right way, highlight it. Share it publicly in other forums.
- Zoom In and Zoom Out – See code reviews from different perspectives. Give reviews at the level of a project, a library, or a function/method. Good code reviews not only look at what has been done, but also the larger context under which the change has been done.
- Watch your tone as it will create the culture and environment in the organisation. Code reviews are not the place for sarcasm, or using a condescending or patronising tone. Such language can make people defensive, and it is important to keep our egos in check. Instead, keep the conversation respectful and constructive, and it will help you create an inclusive environment where different opinions are welcome without showing off.
- If something is a BLOCKER to you, say it so along with the reason why you think so. But be willing to change your mind.
- When you have an opinion, don’t disguise it as a fact. Own your opinions, give your reasons, and be willing to be proven wrong. Don’t write the code review like you know the truth. Instead view it as a journey of discovering the truth together.
- Collaborate / offer to help by sharing a code snippet, pair program, or referring a book/article if required. Don’t just give your opinion and leave the other person to figure it all out by themselves.
- Do not nitpick. Let things go. You don’t have to get your every review comment accepted.
- Talk in person if you can. Walk to their desk, or get on a call. Face to face conversations are always better than having multiple back and forth async text conversations. Summarise decisions and reasons behind them later in the code review tool for others.
- Show empathy in your code reviews – both verbal and written. Aim to understand the other person’s point of view before thrusting your opinion down their throats. Listen them out, and then share your perspective. Appreciate the effort the other person spent in writing the code. Applaud what is good, and be kind and restrained in your criticism.
- Don’t expect developers to fix problems they didn’t cause. Raise a separate story for incremental changes, and assign them to the right person or team. Don’t make it a BLOCKER for the current code review, unless it is something critical with security / financial risk.
- Do not tolerate toxic behaviour – irrespective of how right or smart the other person is. Watch out for brilliant jerks. Encourage them at your own risk.
- Find opportunities for more unit testing , security alerts, dashboards and automation from code review discussions. Code Reviews can be the hunting ground for new ideas to improve your tooling, monitoring, and the larger organisation by adding long term solutions in place. Acknowledge a specific code review for what good ideas came out of it. Make people feel proud about the fact.
- Listen to your team’s ideas on how to make code reviews better. Empower everyone to own the process and suggest and implement changes.
Conclusion
Code reviews, when done well, can be one of the best tools for sharing knowledge, mentoring and learning from each other. Good code reviews also teaches everyone to be a more effective communicator in the workplace.
Once code reviews become a common practice in your organisation, and you have build a decent amount of code reviews with relevant discussions, they can be a tool to empower and teach your new and junior engineers to learn and integrate well in the organisation.
