Python Training by Dan Bader

7 ways to avoid aggravation in code reviews

Thankfully many software companies have adopted code reviews as a best practice these days. An overlooked aspect of how code reviews are conducted is how they can also affect the relationship between engineers negatively.

I believe that it’s important to avoid aggravation in a healthy code review environment. Sure, it feels good to be blunt (and for a long time I thought this was my natural mode of communication). But blunt and unfiltered communication also carries a long-term cost. The communication culture within a team is quickly poisoned by people holding grudges. Even a positive atmosphere can evaporate quickly and then developer productivity takes a hit.

The following 7 points are some best practices for avoiding aggravation that I learned over the years doing code reviews.

#1 – Be humble

Even if you’re the best programmer in the room (I’d say especially if you’re the best programmer), try your best to be humble. Nobody likes an arrogant genius. For example, be honest when you don’t know something and show that you’re not infallible either:

“I’m not sure–let’s look it up.”

#2 – Ask for clarification

Instead of pointing out obvious issues with the code (or what you feel are obvious issues with the code), it’s usually smoother to ask for clarification instead. Say something to the effect of:

“I didn’t understand this bit. Can you clarify that for me?”

#3 – Avoid selective code ownership

The atmosphere you want to create in your team should be one of “we’re all in this together”. A great way to foster that kind of team spirit is by making it clear that all code is owned collectively. Avoid these words: “mine”, “not mine”, “yours”. Instead, use phrases like:

“I think we’ll want to do this in a way that…”

#4 – Avoid hyperbole

I’m super guilty of this one. I like to make exaggerated and hyperbolic statements when I speak with people. That can be really funny when you know someone well and “they get it”.

However it’s something that I’ve cut out of my writing, especially when I do code reviews.

It’s easy for someone to interpret hyperbole the wrong way and feel upset at you as a result. Remember, the relationship with your colleague should be your number one priority.

Avoid words like: “always”, “never”, “endlessly”, and “nothing”.

#5 – Ask questions; don’t make demands

Instead of saying saying “Let’s call that variable userName because it’s unclear”, phrase your suggestion as a question, like so:

“What do you think about naming this userName? The current name felt unclear to me because it’s also used in another context in someotherfile.js.”

#6 – Avoid insulting language

This one sounds like a no brainer. Clearly, no one’s going to insult their co-workers on purpose…

However, it’s more common than you’d think for people to use words like “dumb” or “stupid” in their code reviews.

A good strategy to avoid these “accidental insults” is by assuming that everyone is well-meaning. Most people want to do a good job when they work on something. What seems “dumb” to you was just an oversight or a result of unawareness in most cases.

Also, think of how dumb you will look like when you call someone out on a “stupid” solution and they actually had a great reason to solve the problem the way they did. (I learned this the hard way.)

#7 – Talk in person (or on Skype)

If there are too many “I don’t understand” or “Let’s use this alternative solution” type comments, then it’s time to take the discussion offline.

It’ll save you time in the long run to discuss things in person or on voice chat. Remember to leave a comment summarizing the offline discussion for everybody else.

Give these tips a try!

I hope you enjoyed this list with techniques to avoid aggravating your colleagues when doing code reviews. What were your experiences dealing with relationship issues in code reviews? Let me know on Twitter or shoot me quick email.

<strong><em>Improve Your Python</em></strong> with a fresh 🐍 <strong>Python Trick</strong> 💌 every couple of days

Improve Your Python with a fresh 🐍 Python Trick 💌 every couple of days

🔒 No spam ever. Unsubscribe any time.

This article was filed under: code-review, craftsmanship, and programming.

Related Articles:
  • Should you call out code style issues in a code review? – One of my friends works at a software company where all code changes must be reviewed before they’re deployed to production – I think that’s great. However, he finds that his team spends too much time discussing code style and formatting issues in their code reviews.
  • How to become a better software developer – A while ago I gave a presentation at Mobify’s monthly Engineering Meeting where I spoke about various tactics that can help you become the best software developer you can be. I figured this may be useful to other folks as well and decided to share it in a blog post.
  • How to write a great README for your GitHub project – A great README file helps your project to stand out from the sea of open-source software on GitHub. In this article I go over the key elements every README for an open-source project should contain. It also includes a template for use in your own projects.
  • Should you worry about code reviewing someone more experienced than you? – Doing your first code review for something written by a senior member of your team is scary. As a novice programmer it’s easy to think that only beginning or intermediate developers struggle with this.
  • Watch me do a “live” Python code review for a reader – This is a bit of an experiment – but you might find it interesting!
Latest Articles:
← Browse All Articles