How to do code reviews?

Many young programmers are told to perform code reviews with no preparation, nor explaining how to approach it. They are thrown into the deep end and don’t know how much they can afford to comment on the code created by more experienced colleagues. They end up approving the pull requests after a single scroll, assuming that if the changes were made by a person with more seniority, they are probably right. After all, it can be hard to correct somebody more experienced than you.

On the other hand, we have experienced programmers who, not consciously I hope, torture programming adepts with their code reviews. Seniors tend to comment on bugs in a way that can really stress out the author of the changes. They can even add opinions that create confusion instead of helping. As a result, code review becomes something that people are afraid of, avoid or conduct it superficially.

And I’m not making all this stuff up. I have come across all of this (and much worse) during my many years of a programming career. Therefore, in this article, I would like to share with you some tips and the best practices for code review that might convince your team members to trust you with reviewing code they wrote.

1. Instead of giving orders, make suggestions

When you see a defect in the source code during code review, it often happens that a better solution immediately pops to your mind. You may then be tempted to unceremoniously write it in a comment and indicate to the author of the pull requests how they should correct it in a certain way.

“Use the mapping object, break this function into several others, rename this variable! Yes, now!” This “respect my authority” approach may tempt you, especially if you have much more seniority than the person whose code you are reviewing.

However, when writing a comment, do you think about how it will be received or read?

The author of the pull request will make the change, but the comment itself may be undermining that person – like a patronising slap in the face, pointing to an “obvious” error.

Obviously, everything you write in the comments can be misinterpreted. It is important to make an effort and try to compose your message in a way that has a friendly overtone. You don’t want to be misunderstood or ruin somebody’s day with an imprecise message. If you want people to perceive your messages right, you need to remember the ground rule:

You’re working to perfect the code together, not issue orders around like generals to their privates.

Useful phrases for code review:

• I think it would be better to use a mapper here.
• This function has gotten long, maybe it would be worth breaking it down?
• What do you think about my proposal to rename this variable to…?

As a result of this approach, you may need a little more time to write your comments, but then your code review will feel like a conversation and cooperation between two developers who mostly care about the project’s quality. The bottom line is: the whole point of your comments is not pressing somebody against the wall but politely pointing out things that you think could be improved.

Thanks to this, the newbie programmer feels that there is a place for open discussion and civilised exchange of arguments. It may even encourage them to explain their reasoning and maybe change your mind about something.

Remember – give suggestions and constructive feedback, not authoritative orders.

💡 Read more: A few tips on improving remote team communication culture

2. For better code, don’t write “what” without “why”

In programming, we rarely come across problems that can only be solved in one, specific way. Your comments in code review result from the experience or knowledge you have gained. So when suggesting changes to the code, it’s usually good to write not only what you want to be corrected, but also why you think so. It is about the simple argumentation of your position.

#developer stories #code review #software development