The basis for a fruitful and positive collaboration is respectful and constructive feedback. In this article, I show you 10 actionable tips that help get your code review feedback across in an empathic and compassionate way.
Compassion > Preciseness
In work environments, we tend to focus on productivity. As engineers, we pat ourselves on the back because of our brevity and preciseness.
Still, during code reviews, this isn’t the best strategy. Taking the time to carefully phrase the feedback is crucial.
In my code review workshops, I often see that developers that look at code enter a problem-solving mode. In this mode, they tend to fall back to giving instructions, or a note-taking style of communication.
The results are code review comments like “
Rename to sendMessage."' or
"Remove this. Unnecessary."'
But that’s not the right way to build relationships and collaborate with your peers. Comments like this contribute to a harsh feedback culture and can lead to toxic environments.
So, before you start a code review, you should make sure you take the time to carefully phrase our message, recall that you aren’t giving instructions to a computer, but that you are communicating with other human beings.
Now we can start with the 10 tips to give respectful and constructive code review feedback.
1. Ask question
The best way to foster a positive feedback culture is to ask questions instead of demanding changes. Asking questions about the code has many advantages. It opens up a dialogue and highlights that nobody of the two sides, neither the reviewer nor the code author, is always right.
Asking questions is also less confrontational. This means that the code author and the code reviewer can decide together on the right course of action. It also allows developers to discuss opinionated choices, and learn from each other’s perspective.
Example: Instead of saying:
"This variable should be called 'userId'" you can say
"What do you think about calling this variable 'userId'".
Note: Rhetorical, or feisty questions such as,
"Why didn't you call the variable 'userId.'" aren’t helpful.
2. Make it about the code
When you phrase the feedback, it is a good strategy to avoid addressing the code author directly. Blaming the person instead of the code leads to justification, rejections, and defensive behavior.
Example: Instead of saying
"You did not close the socket connection here." you can say
"This code does not close the socket connection."
3. It’s your perspective
While you should not blame the person writing the code, it is a great practice to use I-messages to indicate that the feedback comes from you. First and foremost this signals that the feedback isn’t a universal statement or a generalization, but an observation, opinion or perspective of you.
Example: Instead of saying
"This code is hard to understand." you can say
"It's hard for me to understand this code."
Also, explicitly stating that this is your view makes the statement always truthful. It’s hard to just argue against it, which makes it easier for both sides to be open to looking for solutions.
4. No Sarcasm
Studies have shown that is extremely difficult for people to detect sarcasm in written language. Even if you believe the other person will understand the sarcastic nature of your comments, research shows people most likely won’t. Therefore, it’s best to leave sarcasm out of your code reviews or any other feedback you give.
5. No Condescending words.
Words such as “just”, “easy”, “only”, or “obvious” can come across belittling and condescending. It’s a good practice to remove those words from your feedback. Most of the time, they do not add any value. A good explanation about the problems caused by those words gives Jim Fisher here.
You can use Alex.js – a linter that integrated with several IDEs – to flag those words for you.
"Why didn't you just write the CSS in a separate file?" sounds condescending and judgemental. Removing the word “just” improves the feedback to:
"Why didn't you write the CSS in a separate file?".
This feedback could be interpreted as coming from a sincere curiosity. But, was this how you deciphered it? Or, did you think it still “sounds” a bit taunting?
Yeah, indeed. Many of us read this message as
"You should have written the CSS in a separate file."
But why? As we do not have additional clues such as body language, facial expression or tone that help us interpret the message, we can interpret this sentence in any way we like. Still, research shows that people have a tendency to interpret written language in a negative way.
6. Use Emoji
One thing that can help here is Emoji. You might think of Emoji as childish or unprofessional. But, they were introduced exactly for replacing the clues that facial expression can give. So, let’s go back to the previous comment, and let’s add one Emoji.
"Why didn't you write the CSS in a separate file"🤔
See, what happened? It’s much easier to interpret this message now as a sincere curiosity.
Still, be aware that Emoji do not make up for harsh or toxic feedback.
7. Explain Your Reasons
If you suggest a code change, then you should also explain the reasons as to why you suggest this change. This is not necessary if you are 100% sure that the code author is aware of the reasons. Still, most of the time adding a short explanation is better than assuming the code author knows your reasons.
Example: Instead of saying “
This code does not close the socket connection.", you can add
"which causes a leak of a file descriptor. Because the socket is bound to an address, no other socket will be able to bind to the same address."
8. Give Guidance
The code reviewer does not need to take over the code authors’ job. Still, it is a good practice to not only critique some aspect of the code but also give guidance on how the code author can improve.
Sometimes this can be a quick note about a method or API that can be used. For example in our socket comment you could add:
"Please use the close()-method to close the connection."
Often guidance is needed more in cases where the feedback is less clear. For example, recall the example where we told the code author that we do not understand the code. Here, it’s crucial that we add some guidance on what the code author can improve to make the feedback constructive.
This means we add to
"It's hard for me to understand this code." some guidance such as
"I think it would help me to have more expressive variable names."
Similarly, guidance is also often needed when critiquing architectural or design changes. For example, saying
"This code should be more performant." isn’t helpful. As a code reviewer, you do not need to come up with the whole solution, but your feedback should briefly layout your improvement strategy.
9. Add Value
Whenever you give code review feedback it is important to be aware of the context. This will impact how much explanation or guidance you need to provide, and can also impact the tone.
To understand how you can add value, you have to consider whom you are giving feedback to. Is this a good friend, a new hire, or a person from another team? How much guidance and explanation do they need?
Also, think out of the box. For example, instead of marking each and every spelling mistake, you could point the code author to a spell checker plugin or offer them to help it install in their IDE.
10. Assume Miscommunication Over Malice
Finally, always assume miscommunication over malice.
As we already discussed, in written communication, the receiver of the message must interpret the message without any natural clues, such as body language, facial expression or tone. Several studies show that this can easily go wrong. Misinterpretations happen frequently and are, in addition, hard to detect on the sender’s side. The best way to limit misunderstandings is to err on the side of caution.
But whenever code review feedback feels harsh or you feel attacked or belittled it is good to take a step back. Let your amygdala – that’s the part of your brain responsible for the flight or fight mode calm down. The remember that most of the time, people have good intentions. With that mindset, you can start addressing the feedback and also helping your peers to convey their message in a more compassionate way.
What next? Read what to focus on when giving code review feedback, how to boost your conflict competence, and about proven code review best practices.
Finally, hop on my newsletter. Each week, I’m writing a well-research email about software engineering related topics. As a thank you, I send you my Code Review e-Book, and you also get access to draft chapters and bonus material of my upcoming Code Review Book.