Three Common Code Review Problems and How to Solve Them

I’m a big fan of code review, but it’s not always easy to get quality code reviews from my teammates:

  • They’re often too busy with their own code to look at mine.
  • Sometimes I’ll miss a number of small mistakes that block them approving my code.
  • They might not have all the context around the code I’ve written, and the code review prompts further discussion to clarify my approach and intentions.

Code reviews are too important to overlook, so it’s crucial to be as good at submitting them as possible. I’ve identified a few problems with code reviews, and techniques that have helped me overcome them.

Problem 1: My teammates don’t understand my code reviews – I have to justify my code.

The code review process is a cycle. You present some code, your teammates give feedback, you iterate based on the feedback, your teammates give more feedback, and so on until you get shipits / +2s / LGTMs / whatever. To get the most out of code review, you want to have as few cycles as possible.

Two easily avoidable factors that increase the number of these cycles are ambiguity (what does this code do?) and confusion (how does this code work?). You can minimize these factors by following these steps:

  • Be explicit. Write a great commit summary that explains the purpose of your review. Compare “This fixes JIRA-1234” to “Feature X broke under circumstance Y (see JIRA-1234) – this commit resolves it by doing A B and C.”. Your teammates will immediately understand your change, and can approve it faster.
  • Know your teammates, and teach proactively. Look at your review and try to emphasize with what your teammates might not immediately understand. Are you using a peculiar language feature, or is the design a little gnarly? In these cases, you should proactively leave inline remarks in the review tool explaining your choices. The more you get to know your teammates, the better you’ll know what to annotate.
    • Example: If you know your teammate has a hard time with JS promises, and your code review uses them extensively, add inline remarks in the code review explaining what you’re doing, or link to educational resources. This will save you a conversation about what the code means, and your teammates will approve your code faster.

Problem 2: My code reviews never get approved straight away – I make too many mistakes!

Code review isn’t a rubber-stamp formality – sometimes your code is going to fall short of the mark. That’s okay! Code review is when your code is assessed against the technical standards and norms of your team, and eventually you’re going to miss something, whether by omission or ignorance.

There are a few techniques I use to make sure the code I show my teammates is as good as possible:

  • Make a checklist. When I started my current job, I would often make similar mistakes in my CSS and PHP reviews. I eventually made what I called a “rigour checklist” as a reminder to check these frequent oversights, and my teammates had much fewer nitpicks after that.
    • For bonus points, automate your checklist. A properly configured linter or other script can catch 99% of issues that your checklist might encompass. For example, frontend engineers can use eslint to catch or automatically fix almost any JS style issue, and postcss is great for uniform enforcement of CSS style guidelines. There are similar tools for almost every language.
  • Be self-critical. I like to do a “self-review” of big patchsets before I ask my teammates to look. I get fatigued when I spend a lot of time in the editor, but my brain switches gears when I look at the same code in GitHub or Gerrit. My perspective is refreshed, I’m more likely to notice mistakes, and I can catch problems before my reviewers do.

Problem 3: It takes too long to get reviews!

Your teammates are just like you – extremely busy, protective of their time – so it can take a while to get the reviews you need. Some tips:

  • Be forthcoming with your reviewers. Posting a URL in the team Slack channel with a brief description is a start, but the personal touch is best; ask each teammate for reviews, particularly if they’re experts in the code you’ve touched. This way they’ll be much more likely to respond. However…
  • …the flip side of being more forthcoming is that you must be respectful. Treat your teammates’ time as you’d like them to treat yours. If your teammates know your patchset’s purpose, urgency, and length, they can budget how long it’ll take to review, plan accordingly, and more accurately set your expectations. If they’re an empathetic engineer, and you follow these steps, they won’t begrudge your request.

Further Reading

In Conclusion

Code review isn’t perfect, but it’s better than the alternatives. Following these tips will help your teammates get the most out of code review, and may even make it a delightful process.

Thanks to Nick Morgan for providing feedback on an early draft of this article, to Si Pham for recommending almost everything in the “Further Reading” section, and to my fabulous teammates for giving great code reviews week after week.