On Empathy & Pull Requests

At Slack, we believe that empathy is humanity’s most important superpower. For our engineering team, that starts when we sit down at our keyboards.

Developing high-quality software depends on high-quality code review from peers. It helps us spot mistakes, avoid duplicating work, and generally ensure better software with less effort. Code reviews are a critical part of the development lifecycle at Slack.

Good code review culture is rooted in empathy for fellow engineers. What do we mean when we say empathy? Well, Brené Brown offers a good starting place — she’s a shame and empathy researcher and professor based in Texas. She defines empathy as having four components:

• to be able to see the world as others see it
• to be nonjudgmental
• to understand another person’s feelings
• to communicate your understanding of that person’s feelings back to them

Empathy is a skill that we have to learn and practice — mastery comes from practice. Ultimately, we want to be warm, be kind, and be accessible. This is the breeding ground for constructive collaboration, and the kind of working style we at Slack embrace.

Empathy in practice: the pull request

So, how can we foster empathy and create a more collaborative environment, especially when a lot of our work consists of us typing by ourselves on our computers? Well, what about code review and pull requests? After all, that’s one of the main ways we interact with our fellow engineers.

It’s very hard to do a job of reviewing code if the author hasn’t set you up for success, so try to do the same for your reviewers. Here are some signs of good pull requests:

Good pull requests give context

First and foremost, good pull requests give context to your reviewer. When you’re creating that pull request, a few things are true:

• You’re happy! You fixed a bug or made progress on a new feature. Rad!
• You have all of the code loaded into your mind: you know what was happening before, and you know what you changed.
• You are ready to move on with your life.

On the other hand…

• Your reviewer was not involved in the fix.
• Your reviewer has no idea what you were doing.
• Your reviewer has no idea what sort of issues you ran into along the way.

Basically, your reviewer is totally missing context, and it is your pull request’s job to give them that context. You have a few options:

• Give it a good title, so people know what they’re getting it into before they start.
• Use the description to tell your reviewer how you ended up with this solution. What did you try that didn’t work? Why is this the right solution?
• Be sure to link to any secondary material that can add more context — a link to the bug tracker or a Slack archive link can really help when describing the issue.
• Ask for specific feedback — if you are worried that the call to the `fooBarFrobber` could be avoided, let them know that so they can focus their effort.
• Finally, you should explain what’s going on for your reviewer. What did you fix? Did you have any trouble fixing the bug? What are some other ways you could’ve fixed this, and why did you decide to fix it this way?

Not every pull request needs every single one of those things, but the more information you give your reviewer, the better they will be able to review your code for you. Plus, if someone ever finds a problem in the future and tracks it down to this pull request, they might understand what you were trying to do when they make a follow-up fix.

Give your reviewer all the context they need to get up to speed with your bug so they can be an informed, useful code reviewer. It’s all about getting your reviewer onto the same page as yourself.

Good pull requests are focused

Each pull request should represent a single task. It’s okay to fix several little things in a single pull request, but they should be related. When your reviewer looks at the files you have changed, they shouldn’t be surprised.

It’s also a good idea to try to keep your pull requests pretty small — your reviewers are more likely to spot problems in smaller pull requests, and it helps avoid code review fatigue.

Good pull requests give confidence

What’s the point of code reviewing in the first place? Well, code reviews let us find problems before they’re problems. So, as reviewers, we should take responsibility for problems in code that we reviewed.

Let’s repeat that, because it’s important: you should take responsibility for problems in code that you approve. If a change gets deployed and causes a bug, it’s your fault, too. Do what it takes to have confidence in the code that’s being reviewed.

If you want people to take responsibility for your code, you better go the extra mile. Fixing a bug is good, but adding a unit test to ensure that it never comes back again is even better. Refactoring code is fine, but keeping the documentation up to date is important. Make sure to cover all of your bases.

In conclusion…

Good pull requests are an act of empathy, for both the author and reviewer.

As the author, adding as much context as possible to your pull requests allows you to not only receive a good review, but engender good will to your reviewer. Good pull requests, ones that are focused, with tests and comments, allow you to safely forget context. As a reviewer, good pull requests allow you to be more efficient, and point your energies at reviewing the code at hand as opposed to gathering context. Everyone wins.

In our next post, we’ll look at the other side of the pull request and talk about what goes into a good code review. Stay tuned!