Code Reviews đź“š

The following is a collection of my thoughts about what makes a good code review. This is a repost from the internal Calypso blog with a few modifications made from feedback. I have also included a few tips to structure PRs in a reviewer friendly way. It’s my hope that this post will help encourage folks to get excited about code reviews.

Frame of Mind

At the start of my career, I didn’t understand why good code reviews were helpful. This was partly because I hadn’t seen a good code review yet. At best someone might have rubber stamped my change, and at worst code gatekeepers nitpicked irrelevant details in the patch leaving both parties in a foul mood.

My thoughts on reviewing changed drastically once I realized I was approaching this with the wrong frame of mind. We are rewarded by what effort we put into it, and as part of that participants must share some common understandings to avoid an unproductive review.

At Automattic, I think we already have a very strong reviewing culture. The following are a few points I personally remind myself, before starting a review.

We all share ownership of the code. It is not yours, or mine, it’s ours. Always welcome improvements and share knowledge freely.

Many programing decisions are opinions. There is often no one right answer. Discuss tradeoffs in a productive way and move on quickly. Stick with project convention for stylistic things like tabs vs spaces, even if you don’t agree with it. Changing convention can be done outside of the PR as a larger discussion with the group.

We can always learn new things. No matter how much one knows, we can always learn more. Folks can expose you to new ideas. Explaining concepts you’re familiar with can help improve your understanding of it.

Communicating

Another huge part of a successful code review is good communication. We’re all nice folks at Automattic, but text communication is tricky. It is very easy to misinterpret feedback about code as something more personal. I think we’ve done a very good job at avoiding this, but here are a few techniques to lesson confusion.

  • Avoid separating code ownership. Do not assign ownership of the code with words like “my code” or “your code”. Doing so makes code reviews feel more like a personal judgement. We all share ownership of the code. Remember that the code is also a product of many constraints (time, familiarity with the codebase, etc.) and is not a personal reflection about the author. Even the best developers will produce code from time to time that has some issues to work through.
  • Assume best intent, stay positive. Avoid sarcasm and negative descriptors like “terrible” or “dumb” that may be misread.
  • Avoid demands, offer suggestions instead. “What about moving this into it’s own file?” It’s also helpful to phrase these as questions. Often times the reviewer may be missing context on why a particular suggestion will not work.
  • Authors should respond to suggestions. “Great catch! Updated in 565acae.” “We went ahead with the original approach because of timing concerns.”
  • Be explicit. “Let’s do change X because of reason Y”
  • Say if something is a blocker or optional. “Due to security concerns we should update this method before shipping.” “This is optional but I think this reads better if we move this into it’s own method.”
  • If something is confusing, ask. “What is the reasoning behind these changes?”  “I don’t understand what’s happening on this line, could you please explain?
  • Let the author know when you appreciate a change. “Thanks for taking on this task!” “I really ❤️ how this new workflow feels, I left a few notes on some things we can improve.” “This PR drops our build size by 500kb! Great work!”
  • Explain next steps, or complete the review. “I noted a few blockers I’d like to see resolved before we 🚢” “Changes here look great. 🚢 when you’re ready.”
  • Keep up momentum. If a PR looks stalled ask if anything needs to be done. This is especially important for OSS contributors. It is usually better to accept a PR that has a few issues left to work through, and fix it up later, than have the OSS person abandon the PR.

Preparing your PR to be Reviewed

If folks are always waiting for a code review it helps to have some empathy for the reviewer too!

  • Explain why. Assume reviewers have little or no context when reading the PR. Explain why we need this PR and what it does. (This is also very useful when looking at past decisions). Screenshots and gifs are appreciated when behavior is complex.
  • Add Step-By-Step Test Instructions. Can someone unfamiliar with the changes test your PR by reading the summary?
  • Keep changes small. Large changes are difficult to review and understand. Try to separate janitorial changes from PRs that change behavior.
  • Note weird things. This includes explaining any odd code workarounds, or buggy behavior. This can save some back and forth between the reviewer and author, and may also expose existing bugs.

Code Review Benefits

When done well, code reviews can help on many different levels.

  • It spreads code ownership.
  • Communicates changes across teams.
  • Serves as a sanity check to verify that requirements make sense.
  • Allows folks to find bugs though both manual testing and in code.
  • Lets all folks involved learn new things!
  • Can also serve as documentation for how something worked, and why certain decisions were made. Perhaps even for a future you!

Anyone can be a Reviewer!

The fact that code reviews work on many levels also means that reviewers don’t need to know all things about a project in order to make a meaningful contribution. Sharpening copy, manually testing, polishing design, or asking questions about confusing things is a great help.

Code Review Challenge

If this isn’t a habit for you yet, I’ll like to challenge you to try reviewing a few PRs from a different team or one that you may have felt intimidated to contribute to.

Here are a few strategies I use to pick PRs to review:

  1. Take a look at one of the oldest PRs on the needs review list. Ping the author with questions if it looks inactive.
  2. If you don’t have a lot of time, choose a tiny PR to look at. These are the fastest to review and test, and usually have the least risk of causing a regression.
  3. Choose something you’re unfamiliar with. Reviewing PRs is a great way to learn, and to keep a pulse of what’s happening on other teams. Don’t be afraid to dive into a section you’ve never looked at before. If you don’t follow, or something is unclear, ask questions! The PR author is usually happy to explain.

Have fun reviewing!

Work and other things

I work for Automattic a completely 100% distributed company with employees from all around the world. Once a year we hold the Grand Meetup, a frenetic week long event where the whole company flies in to blanket an unsuspecting off-season ski resort with our own wifi and friendly Automatticians.

It’s a crazy-fun experience, and one of the rare chances we get to see the folks we work with in person.

team

My awesome team

 

While at the meetup, I got a lot of enthusiastic thanks from folks for helping out on reviewing their pull requests. It was extremely flattering, but I also had the nagging thought of “Is it so unusual for cross-team reviews to happen?”

So Many Pull Requests

stack.gif

To give some more context, I primarily work on Calypso, an open source dashboard for reading, writing, and managing all of your WordPress sites in one place.

At any given time there are roughly 3-5 pages worth of PRs with a needs review label. This is pretty overwhelming. I can understand how easy it could be to have tunnel vision and only keep track of your teammate’s work.

To encourage folks to review a bit more, here’s a quick summary of how I break up my day:

Morning – review all the things!

I happen to work in the latest time zone on my team. This means that by the time I’m online, the rest of my team already has a number of in-progress or needs review PRs that are fresh and waiting for me. This is one of my only chances to chat with folks while they’re also awake, which makes it a great time to catch up with folks or have a live video hangout.

My morning time is very interrupt-driven, which is why this is also the best time of day for me to review my team’s PRs. I have a special email filter for Calypso pings. I try to run an inbox-zero approach here, but depending on current project needs I might not be able to get through all of them.

coffee.gif

Coffee and Breakfast is also very important

 

Afternoon – Coding

By the time I’ve finished lunch, the rest of my team should hopefully be relaxing as their day winds down. Slack is mostly quiet in my afternoons, aside from helping out with a random Calypso fire or two that may occur from time to time. I usually have a solid chunk of uninterrupted time, which is great for getting into the flow, loading a complex problem into your brain, and cranking out a decent approach to a problem.

I stop when I’ve hit a good point, where I’m pretty certain I won’t be dreaming about solving the issue in my sleep.

code.gif

Evening – Trash Pickup or Cross Team Reviews

After hitting a good point with my in progress issue, I usually have a little bit of time left in my day. To wind down, I might pick out a quick janitorial issue to hammer out, or more often I might peruse that giant list of PRs that need to be reviewed:

giphy-1.gif

But how to pick one?

Picking a PR to Review:

Here are some suggested approaches:

  • Take a look at one of the oldest PRs on the list. Ping the author with questions if it looks inactive.
  • If you don’t have a lot of time, choose a tiny PR to look at. These are the fastest to review and test, and usually have the least risk of causing a regression.
  • Choose something you’re unfamiliar with. Reviewing PRs is a great way to learn, and to keep a pulse of what’s happening on other teams. Don’t be afraid to dive into a section you’ve never looked at before. If you don’t follow, or something is unclear, ask questions! The PR author is usually happy to explain.

Always Waiting for a PR Review?

Do you always feel like you’re waiting for a review? A few tips:

  • Add context and reasons of what your PR is trying to achieve in the summary, so someone unfamiliar with the issues can hop in and help.
  • Add step-by-step testing instructions! This makes it easy for people to review your code.
  • Break down huge PRs into manageable chunks. Large diffs are incredibly hard to review and test, and it’s more likely that folks just don’t have that amount of time to sit down and attempt to understand the PR.
    • The might mean adding wip PRs with feature flags
    • Sorting out janitorial things, like updating code-styles into their own PRs
    • Do things in steps. For example, first creating a PR to add a new component, before using it on a page in a second PR
  • Take some time to review a few PRs! Other folks are waiting too!

Night – Relax!

Your day might look very different, but I find that interrupted time is great for PRs, and quiet time is incredible for coding.

Remember to take it easy though and not to overwork yourself. I personally try to work somewhat traditional hours and turn on a do-not-disturb mode on my phone for night time hours. This helps me from from getting sucked back into work mode too late at night. Other folks might be able to handle a much looser schedule, but I am not one of them. 🙂

Anyway, I hope this post was helpful! To my co-workers it was great seeing you at the Grand Meetup, and I can’t wait to see you all again!

bear.jpg