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 insomeotherfile.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.
