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.
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.
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.
We want to avoid a situation where:
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.
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:
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.
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”
“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 🙂
Promyze, the collaborative platform dedicated to improve developers’ skills through best practices sharing and definition.
Crafted from Bordeaux, France.