About the author

Will Barrett is a Software Engineer, Technical Lead, and Engineering Manager from the San Francisco Bay Area with over 14 years of experience. Will is a member of the Project Management Committee for Apache Superset. He’s held staff software engineer and senior engineer roles at Change.org, Entelo, Sqwiggle and Preset.

Will is the author of On Learning to Program, a blog for new Software Engineers entering the industry. Will is also a certified reviewer on PullRequest where he’s caught hundreds of bugs and other critical issues for over 30 teams.

Have you ever had a conversation on a pull request that just went sour? One that left everyone feeling conflicted, hurt, and angry? I wish it weren’t the case, but I’ve seen this play out multiple times over my career and even participated once or twice. Like any other human interaction, code review can be fraught. Misunderstandings and conflict are bound to arise. When they do, leading with empathy can help defuse conflict and put the team back on the right path to success.

Code Review is Asynchronous Communication

Code review is generally done asynchronously, even when everyone is working from the same office. An Engineer is looking over the result of someone else’s work and providing written feedback. It’s important to think about code review as remote communication - the emotional content of face to face interaction is not present. This means that a factual statement made by one Engineer can be interpreted differently, and may be perceived as hostile unintentionally.

Communicate Positive Intent and Build Discussions

Feedback in code reviews is often constructive in nature, so it’s important to make efforts to communicate in a positive way, and think about how comments will be received. A small amount of time couching a suggestion in more positive language can greatly improve the tenor and outcome of the whole conversation. Adding qualifiers such as “Have you considered…”, “Do you think it would be possible if…”, and “Under these circumstances, I think this might happen…” can help make the other person a participant in the conversation, rather than the recipient of directives or criticism.

Recognize the Existence of Multiple Correct Solutions

Very rarely is there only one way to solve a problem with code. Usually there are multiple valid paths to a workable solution. When possible, see as much validity in the solution under discussion as possible. The author likely had reasons for taking the approach they did. Remember to ask for them if they are not immediately apparent! When this context is lacking between members of the discussion it can frequently lead to hurt feelings.

Understand the Business Context for the Change

Is Production offline? If so, this might not be the time to pay too much attention to code formatting or architectural perfection. Try to calibrate the content of your review to the situation at hand - understand when the team is taking on debt intentionally to meet a deadline and when it’s time to make sure the code is as perfect as possible. Bringing the wrong type of feedback at the wrong moment can be counter-productive. Think about whether the feedback being given should block the merge of the change or whether asking for a followup PR would make more sense given the issues of today.

Refer to Sources of Truth

Bringing in links to documentation, code samples, industry articles, and internal metrics can help move the conversation from one focused on preference and opinion to one focused on the facts of the current situation of the system, the business, and the technological environment.

Give Compliments Where Compliments are Due

Code review is not just for catching the issues, it’s also for praising the good. Make sure to sprinkle compliments into your reviews - it will cultivate goodwill, but also it’s the right thing to do. Make sure your colleagues know you are cheering for them, not just watching and waiting for them to slip up.

Say Thank You

Gratitude is one of the great motivators in the world. Think about the experience your colleague had in doing the work. Were they going after a hard task that was really tricky to accomplish? Thank you. Did they find and fix a bug that no one else had noticed? Thank you. Were they working on some legacy code with no test coverage that everyone on the team is afraid to touch? Thank you. Saying thank you is free and it communicates to your colleagues that you appreciate their presence every day and you appreciate their work.

Don’t be Afraid to Pick Up the Phone

When a conversation is becoming heated, or it’s difficult to understand what’s being suggested, one of the best things to do is switch to synchronous communication - either in-person or video if possible. Seeing the expressions on a colleague’s face can help defuse tension and remind the participants in the discussion that the relationships on the team and the outcomes for the organization matter more than the specific subject under discussion. Empathy is fostered more effectively through synchronous communication than through text.

Disagreement is Inevitable, Conflict is Avoidable

Engineers bring different life and professional experiences to their work. Different lessons learned over time lead to different worries and priorities between Engineers on every team. Add in the pressure of deadlines, competition for promotion, and the ever-present danger of technical failure and the ground is fertile for conflict to grow. How we communicate with each other and how disagreements are navigated is what determines whether there will be conflict or productive discussions. Hopefully some of the ideas in this article will help you build a better rapport with your colleagues and bring more empathy and joy to your code reviews.

Image by Victor Del Bono