How About Code Reviews?

Last time, we talked about empathy and what goes into good pull requests. This time, let’s talk about the other side of the equation: what makes a good code review?

Why are we doing this?

First, it’s important to remember why we’re bothering with pull requests and code reviews in the first place.

• They offer us an opportunity to share and explain our work.
• They give us a place for feedback.
• They demonstrate that we are responsibly managing which code we ship to our users.
• They give us a chance to teach (by introducing people to a new part of the code) and learn (by receiving feedback).

Each of those reasons is different, but the same strategies are important for all of them.

Good code reviews are not rushed

Take your time. Relax. Drink some coffee.

Code reviews aren’t a distraction from your job: they are your job. You are here to help build an amazing product, and ensuring that we all do a good job is an important part of that.

Good code reviews are confident

If you’re new to the project, you will probably not feel comfortable reviewing code at first. That’s okay! You’ll probably feel confident saying “not okay” sooner than you will feel confident saying “yes, ship it!”, and that’s okay, too.

Make sure you know your own comfort zone. An approval without any confidence behind it isn’t really worth much.

Good code reviews are not superficial

People who are new to your project might need a helping hand in getting used to your project’s coding style, but in general, reviews shouldn’t be too focused on superficial issues like code formatting. Readability still matters, of course, but try to focus on the big picture. Consider whose code you’re reviewing and try to anticipate what they need.

Good code reviews require understanding

If you don’t understand the code being changed, go read the current version. If you still don’t understand, ask questions. Make sure you really understand. At the end of all that, if you feel totally out of your depth, that’s okay: pass the review on to someone who has more context, and follow-up on it later so you can learn.

Asking clarifying questions can help the author of the pull request understand better, too. Talking about the changes and bringing up edge cases are some of the most valuable things you can contribute to a code review.

It can be helpful to summarize your understanding in a comment — putting your thoughts into words will help you solidify that understanding, and it will also let your reviewer know that you’re paying attention.

Good code reviews share knowledge

Does this bug seem familiar? Is it touching some code you were in recently? Maybe you can do more than just review their branch.

Share your knowledge. Reference old bug reports. Solve the problem at a deeper layer. When you work with another person on something, you both get better.

Good code reviews are not huge

If you find yourself writing more than a sentence or two, or fundamentally disagreeing with a big part of the work that was done, or going back-and-forth with the other person, maybe code review isn’t the right place for the conversation. Go talk to them one-on-one so you can get onto the same page.

In general, rather than ambushing someone with a huge list of public comments, consider talking to them privately. This leads into our final topic…

Good code reviews have empathy

Finally, and most importantly, the awkward, fuzzy part: be empathetic. Remember, there are four components to empathy:

• 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

If you see a problem with the code, try to put yourself in their shoes and try to help them see the problem without making them feel like a screw-up. Even experienced developers flub this part sometimes! It’s super hard. Sometimes, you will make mistakes. It’s okay — just work at it.

The way you write is everything. Don’t correct people — ask them for clarification. Assume they know something that you don’t. This is a really important thing! Assume that your co-workers are smart and are doing a good job.

Written communication can be tricky — it’s missing a lot of the social clues that let people know what you’re thinking. It’s easy to put people on the defensive, so take the time to try to use empathy words. — “us”, “our”, “we” are much better than “you”, “your”, and “mine”. You’re all on the same team, after all.

In conclusion

Pull requests & code reviews are where code meets people. It’s about communication more than it is about code, so take your time, do a good job, and think of the human being on the other side of the pull request. Good luck!