Best code review practices: 5 errors to avoid

Best code review practices intend to help developers’ teams to have a great experience with code reviews. This practice has many benefits for a team. This post focuses on 5 mistakes to avoid when doing code reviews.

#1 Forget to highlight well-written source code

Show empathy. Developers who spent several hours/days working on a task feel the code review step as a first achievement, even though they’re likely to rework the code after the review. However, a common mistake is to focus only on negative points that need rework.

As a submitter, I do appreciate comments saying some parts of the code are well-written. We tend too often to blame people when they don’t do their job correctly and say nothing when they do it correctly. Which happens more than 95% of the time. Some would say “it’s normal to do our job correctly; that’s what we’re paid for.”. I do agree, but honestly, it does not cost too much time & energy to have some kind words for our colleagues.

So don’t be stingy with such comments! This is clearly one of the most relevant best code review practices.

#2 Miss the capitalization part

If you write a comment and think: “I’m sure someone will make the same mistake later”, ask yourself how you can avoid this situation. Is it because this knowledge is not spread enough yet? Should some technical documentation be updated? Think “Capitalization” will save you time and energy in the future. Recent code review studies indicated that developers could feel tired because of repetitions and this “endless-day” effect.

Tools like Promyze provide web browsers plugins that enrich the user experience on pull/merge requests and make it easy to create a best practice and share it with their team.

#3 Be afraid to share your doubts

We want to avoid a situation where:

• the submitter is not confident about their source code
• the reviewer is unsure or not clear about the understanding of the source code
• the reviewer thinks the submitter is fully confident in their source code
• the review is validated, the PR/MR merged, and suspicious code is in production.

Some people can feel embarrassed to admit they didn’t get a 100% clear understanding of a source code. They don’t want to show a kind of weakness to their colleagues.

Remember: It’s completely fine to say “Sorry, but I don’t get your point.” This is likely because the way it’s been explained could be improved. Psychological safety is probably the top factor for successful engineering teams.

#4 Do the review while you’re not ready

If you’re tired or not in the mood, it’s okay to admit it. Maybe another dev can take the review? Or can we wait until tomorrow? In any case, being superfluous has no added value:

• the submitter will probably feel it, which is not a nice feeling;
• you increase the risk of increasing bugs or code defects, which is clearly something we want to avoid.

You’ll be excused from being in a rush or having a heavy mental load. I barely talk to developers that get bored! It’s better to find a trade-off and identify when you’ll be available to perform a great review.

#5 Indicate issues without suggesting an alternative

One goal of reviewing source code is to identify potential improvements in the source code. However, the way you explain your point of view is important. Avoid formulations like:

“You shouldn’t call this method like this”

But instead:

“I’d suggest calling this method like this: []. This is our standard in the project”.

Don’t write dozens of words, but give values to the code’s author. Ask yourself if reviewing your comments provides enough material to rework the code easily.

That’s all folks for the topic of best code review practices. Feel free to share with us some common pitfalls and bad practices you’ve experienced with code reviews 🙂