Maximizing the Value of Code Reviews: A Guide for Reviewers
It’s 3:00 PM and the calendar notifies you that it’s time for your daily code review meeting with yourself. For many of you (including myself), the first thought that runs through your head is “Well, I’ll just finish my tasks and get to it later” (‘later’ means ‘tomorrow’).
But if you ignore that thought and grab a cup of coffee, you’ll find a great opportunity to be involved in the professional process of other engineers and improve yourself because of it.
Keep reading to find out how doing code reviews can be beneficial and learn about my best practices for reviewing code.
What I gain from doing code reviews
Code review is one of the most common ways of gate-keeping code, keeping it clean of bugs, maintainable, and aligned with the company’s standards and architecture.
In addition to that, let me tell you why else I do it:
- Become a better developer
Code reviewing gives me a great set of skills like paying attention to the small details, keeping in mind the code’s readability, and being familiar with the company’s coding guidelines. While doing code reviews, I read technical articles to support my comments, I practice reading and understanding the code of other developers, and of course, I learn tons from others.
By developing my reviewing skills, I’ve become more aware of my own code quality and how to improve it. - Build professional confidence
I think that the first time I felt my professional confidence rise was when I started to do code reviews. I realized that my opinion matters, that I have good comments to suggest, and that developers, at any level, can learn something new from me. That can be a really big boost to self-confidence and drives me to keep up the good work. - Improve your reputation
As an individual contributor, I find code reviews a wonderful way for me to influence others and “silently” build my leadership skills from the ground up. By dedicating my time to communicating with my teammates, consulting them, and voicing my professional opinion during the code reviews, I gradually build their trust and their will to consult with me on any dilemma they might have, even beyond the code review time itself.
My best practices for providing code reviews
Code reviews have a special place in my heart. Over the years, I have developed an approach that leads me every time I review a code, and I’m glad to share it.
I’m going to refer to code reviews of Github pull requests (PRs) in particular, but you can definitely apply them to any tool or format of code reviews that you wish to use.
Every pull request has a title. And a description. And sometimes an image.
Before diving into the code review itself, I start with a simple, yet crucial step: understanding what the PR is all about. I found out that when I understand the context of the PR and its goals, I’m able to pay attention to small details and identify potential issues.
In order to get into the context, the first thing that I do is read the PR title and the description.
They’re not there? I request them.
They’re not clear enough? I ask the developer to refine them.
Does the PR include a UI change? I ask for an image or a short video that demonstrates it.
A good title and description help focus on the idea of what we’re about to review, and it also encourages my colleague to be more explicit.
And a cool bonus: it creates wonderful documentation of our work.
Always give a reason
This is one of my main points, and I would like to start with an anecdote: as a developer, I experienced code reviews where the reviewer just commented the word “NO” (sometimes accompanied by an angry emoji). I had absolutely no idea what I did wrong, or what was expected of me to change, and in the end, it just made me feel frustrated. From that experience, I came up with the following strategy:
for every comment that you give, explain why you suggest it.
This approach serves both sides in so many ways:
- The developer might learn something new that can be useful for the future.
- Providing a reason raises your credibility as a reviewer and might make the developer more dedicated and cooperative.
- If you can’t find a reason why you asked for a change, then maybe this change is not needed at all. Or maybe it should be just a suggestion. Anyway, it’ll help you sound less nitpicking and more reasonable.
- In case the developer doesn’t agree with you, he already knows your motivation for requesting the change and he will know how to refer to it. It’ll save time for you both.
I think there are many more reasons why providing a reason can be beneficial, but at the end of the day, when a colleague told me that she learns a lot from my explanations of why I’m asking for a change in the PR, well… fulfilling is the word.
“Reading a story“ state of mind
There are many great articles that talk about the importance of code readability, so I’ll just give a tl;dr of them:
Code tends to be revisited. The idea of readability is to help the developer that revisits the code to easily understand what this code does.
And that’s where the reviewer enters the picture. As a reviewer, I’m probably the first person to read this code objectively. I’m coming with a full context of what this code is supposed to do (because, as you remember, I read the PR’s title and description 😀), so I take this opportunity to examine the code, readability-wise. I usually do that by asking myself the following questions:
- How much do I struggle to understand what’s going on here?
- Can I browse this code and understand the general idea of what it does, without getting into details?
- If I would read this code without reading the PR description, would I understand what it does?
I utilize these answers to suggest ideas of how to improve the code readability, for example: renaming variables, simplifying a complicated piece of code, exporting code lines into a named function, and so on. By reviewing the code from a readability perspective, I enable the team to move faster and to have a better developer experience along the road.
Be polite, nice, and funny (but in a good way)
Let’s face it, a code review is a conflict by design. It can start with a small disagreement and can easily escalate to an unpleasant argument.
To avoid these hurdles, I always keep in mind that there’s a real person that has worked really hard on the code that I’m about to review. Thus, I try to be sensitive, respectful, aware of my intonation, and polite, without writing something that might sound offensive.
I think that by making this process fun and breezy, we can seize this opportunity to get closer to our teammates. Here are some ideas that work for me:
- Appreciation is the keyword: If I see a piece of code that I like, I mention that in a comment. The developer will definitely be glad to read that. If I see that the developer implemented in advance a suggestion that I gave in a previous PR, I express appreciation that my comments were taken into account.
- Gifs: While reviewing a code, I take a minute to pick a gif and attach it to the review. It’s always fun to do that, and the other side always smiles when he sees a gif that was dedicated to him. Let me tell you something: if you make people anticipate your reviews to see which gif you picked this time, you have definitely succeeded in making this process more delightful.
By making this process fun and positive, we create a pleasant atmosphere and build our reputation as people that other people are happy to work with.
So yeah, that’s about it
I hope that this post has inspired you to take your code review routine to the next level. From personal experience, I can say that following these guidelines helps my team produce better-quality code, promote a culture of continuous improvement, and of course, deepen the relationship between us.
