Respectful and constructive code review feedback is the basis for a fruitful and positive collaboration. In this article, you learn 10 actionable tips to get your code review feedback across in an empathic and compassionate way.
Compassion > Preciseness for code review feedback
In work environments, we 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 code review feedback is crucial.
In my code review workshops, I often see developers who are reviewing code get into a problem-solving state of mind.
In this mode, they fall back to a note-taking style of communication.
This results in code review comments such as Rename to sendMessage. or Remove this. Unnecessary.
But that’s not the right way to build relationships and collaborate with your peers during a pull request. Comments like these contribute to a harsh code review feedback culture and can lead to toxic work environments.
So, before you start a code review, make sure you take the time to carefully phrase your feedback. Recall that you aren’t giving instructions to a computer but communicating with other human beings.
Now, let’s deep dive into the 10 tips to give respectful and constructive code review comments.
1. Ask questions during code review
The best way to foster a positive code review feedback culture is to ask questions instead of demanding changes. Asking questions about the code has many advantages. It opens a dialogue and acknowledges that 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 ask, “What do you think about calling this variable userId?”
Note: Rhetorical or feisty questions when commenting on pull requests, such as “Why didn’t you call the variable userId?” aren’t helpful.
You might think that asking questions is not constructive code review feedback, but in fact, it is. It helps the code author to reflect and think about your input without getting defensive.
2. Make it about the code
When you phrase the code review feedback, it is an excellent 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."
Blaming is never constructive code review feedback and won’t get you and your team far. See code reviews and coding as a team sport. Focus on facts and leave the blame game out of code reviews.
3. Clarify that it’s your perspective
While you should not blame the person writing the code, it is a good practice to use I-messages to show that the code review feedback comes from you. First and foremost, this signals that the feedback isn’t a universal statement or generalization but your observation, opinion, or perspective.
Example: Instead of saying, “This code is hard to understand,” you can say, “It’s hard for me to understand this code.”
Explicitly framing the comment as your view makes it more constructive because it distinguishes your experience from a universal claim.
For example, if you say, “Longer variable names are always better,” the code author might disagree. The statement presents an opinion as a universal truth and generalizes with the word “always.” If you say instead, “I find longer variable names easier to understand,” you turn the comment into constructive feedback. The author might still disagree, but at least they have learned something about your perspective.
It’s hard to argue against your perspective. This makes it easier for both sides to be open to looking for solutions.
4. No sarcasm when reviewing code
Research on email communication shows that people can misread sarcasm in writing and that senders tend to overestimate how clearly they convey it. Even if you believe the other person will recognize a sarcastic pull request comment, they may not interpret it as you intended. Therefore, it’s safer to leave sarcasm out of code reviews and other written feedback.
5. No condescending words
Words such as “just,” “easy,” “only,” or “obvious” can come across as belittling and condescending. It’s a good practice to remove those words from your code review feedback when they do not add meaning. Jim Fisher gives a good explanation of the problems these words can cause.
You can use Alex.js, a linter with integrations for editors and CI tools, to flag potentially condescending language such as “obviously.”
Example: Why didn't you just write the CSS in a separate file? sounds condescending and judgmental. Removing “just” improves the feedback: Why didn't you write the CSS in a separate file?
This feedback could be interpreted as sincere curiosity. But was that how you interpreted it? Or did it still sound a bit taunting?
Yeah, indeed. Many of us read this code comment as "You should have written the CSS in a separate file."
Why? In written communication, we do not have additional cues such as body language, facial expressions, or tone of voice to help us interpret a message. As a result, readers may understand a sentence differently from how the writer intended it.
6. Use emojis carefully in your code review comments
Emojis can help convey tone when written feedback lacks facial expressions and body language. However, their interpretation varies by emoji and audience, so use them only as a supporting cue—not as a substitute for clear wording.
Would you be open to moving the CSS to a separate file? 🤔
Here, the wording carries the respectful question; the emoji only supports its tone.
Still, be aware that emojis do not make up for harsh or toxic code review feedback.
7. Explain your reasons for the requested PR change
If you suggest a code change, then you should also explain the reasons why you suggest this change. This is unnecessary if you are 100% sure that the code author is aware of the reasons. Still, most of the time, adding a brief explanation to your pull request comment is better than assuming the code author knows your reasons. This differentiates plain criticism from constructive code review feedback.
Example: Instead of only saying, “This code does not close the socket connection,” explain the consequence: “Leaving the socket open can leak system resources and keep the connection open longer than intended.”
8. Give guidance during code reviews
The code reviewer does not need to take over the code author’s job. Still, it is good practice not only to critique an aspect of the code but also to guide the code author toward an improvement.
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, code authors need guidance when the feedback is less clear. For example, recall the example where we told the code author that we did not understand the code. Here, it’s crucial that we add some guidance on what the code author can improve to make the code review feedback constructive.
This means adding guidance to “It’s hard for me to understand this code,” such as “I think more expressive variable names would help me understand it.”
Similarly, code authors need guidance when reviewers critique architectural or design changes. For example, saying “This code should be more performant” isn’t constructive. As a code reviewer, you do not need to come up with a complete solution, but your feedback should briefly lay out your improvement strategy. Again, this differentiates unconstructive from constructive code review feedback.
9. Add value for the code author
Whenever you give code review feedback, it is important to be aware of the context. This will affect how much explanation or guidance you need to provide, and can also affect the tone.
To understand how you can add the most value for the code author, consider whom you are giving feedback to. Is this a colleague you know well, a new hire, or someone from another team? How much guidance and explanation do they need for this code change?
Also, think outside the box. For example, instead of marking every spelling mistake, you could point the code author to a spell-checker plugin or offer to help them install it in their IDE. That way, you can focus on giving respectful and constructive code review feedback instead of performing tasks that tools can do better, faster, and automatically.
10. Assume miscommunication over malice
Finally, always assume miscommunication over malice during code reviews.
As we already discussed, in written communication, the receiver of the message must interpret the message with no 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 during a pull request, it is good to take a step back. Give yourself time to calm down before responding. Then remember that, most of the time, people have good intentions. With that mindset, you can address the feedback and help your peers convey their message more compassionately.
What’s next? Read about code review challenges that slow teams down, the fundamentals of effective code reviews, and proven code review best practices.
Finally, join my Awesome Code Reviews newsletter for research-based insights and practical guidance on code reviews and software engineering. If you want to follow my upcoming Code Review Book, you can also join the early-reader group.
