8 Code Review Tips to Merge your Pull Requests Quicker

As a young engineer I used to have this terrible misperception that if you’re not coding, you’re not working. So, naturally, I spent as little effort as possible crafting my pull requests. I’d open these god-awful PRs with comical amounts of code, anemic descriptions and no guidance for reviewers. Needless to say my code didn’t get reviewed or shipped very quickly.

I’ve matured a bit since then and along the way I discovered a few tricks that have helped me create PRs that are easy to review, get my code shipped faster and build trust amongst my team members. Here’s what I’ve learned:

1. Consider The Reviewer

This is the most important tip because every other tip in this article stems from this idea. It’s tempting to get so engrossed in the coding that you forget that someone’s going to review your work. As the PR author, you are responsible for getting your code to production, so it behooves you to consider about the person or persons reviewing it.

The mantra I repeat in my head is “Make the reviewer’s job easy”. There’s plenty of ways to do this and I’ll go through some in this article but the key here is to be actively thinking about the reviewer while you’re coding and when you’re drafting your PR. Putting yourself in the reviewer’s mindset is the first step to creating better PRs.

2. Keep It Small

Large PRs require more cognitive overhead. This makes a reviewer’s job harder not easier. When you open a really big PR the reviewer will do one of two things:

1. They’ll apply the same level of diligence that they apply to all PRs. This means it will take longer to review. Review time doesn’t scale linearly as a PR gets bigger. It actually scales super-linearly because the cognitive overhead required for review compounds on itself as the PR grows.
2. They’ll apply a lower level of diligence than they apply to smaller PRs. Because a huge PR is daunting the reviewer sort of gives up. (I’ve definitely been guilty of this). A more cursory review will certainly be quicker, so this might sound like a good thing, but of course it’s not. The bigger the PR, the riskier the deliverable. And if the reviewer “gives up” by providing a cursory review, that deliverable just went from risky to dangerous. Sure, you might ship your code faster, but you’ll more than make up for it fixing production bugs.

Before you start coding think about how you could break up your work into smaller deliverables. Not only is this good for code review but also allows you to ship smaller pieces to production, so if there are bugs (and there are always bugs) it’s easier to track them down.

Sometimes, it’s not possible to break up your work into smaller pieces. If you do need to open a large PR, hopefully some of the other tips in this article will help make the review process faster. That said, try really hard to break up your work into smaller PRs. A large PR is a last ditch effort, not an excuse for lazy planning on the part of the coder.

3. Review Your Own Code

It sounds silly since you just wrote the code. You know what it does and how it works. Isn’t the whole point of code review to get another set of eyes on it anyway? Sure, but your present self is a different set of eyes than your past self. When you make a new PR in Github you can see the entire diff before you actually open the PR. Take this opportunity to look through the code you’re about to unleash upon your team members. And, because you wrote it, you already have all the context one needs for the review; this should make a self review pretty quick. You can catch small mistakes much faster than someone else can.

Again, going back to making the reviewer’s job easy. I can’t tell you how many times I’ve found a debugging statement I forgot to remove or a method I created that I never ended up calling. By removing all the cruft, I can let the reviewer focus on the substance of the PR, not my silly mistakes.

4. Write a Good Description

As we’ve already discussed, the larger the PR, the harder it is to review. The PR description in Github is a great place to provide some high level information about your PR. While a one line hot fix probably doesn’t need much description, a medium to large PR can really benefit from a good description. Here’s a few suggestions for what you might want to include in your description:

• A justification for why you made the code changes you made. Not everyone reviewing your PR will necessarily already have context as to why you’re making these changes.
• A summary of the changes you’ve made. This can help reduce cognitive overhead for the reviewer. If they dive into your code with a high level understanding of how all the pieces fit together, it makes their review easier.
• An explanation of why you coded it the way you did. You may have made implementation or architectural decisions that the reviewer may disagree with at first glance, but if you explain your rationale you can pre-empt a comment from the reviewer.

5. Add a Visual Description

It’s not just other engineers that will look at your PR. I’ve had designers and product managers ask me to include them on a PR. They may not review your code but they still deserve to know what’s going on. If you’re working on a feature with a visual component, it’s great to add screenshots or a screen recorded gif to your PR description. I’ve had designers and product managers catch bugs just from my screenshots. This also helps keep the non-engineers in the loop about where work is in the dev pipeline.

6. Add Inline Comments

Just like descriptions, this is an opportunity to pre-empt a reviewer’s comments. While the description is great for high level explanation, inline comments are great to point out specific areas of the code that you think could be contentious or cause confusion. Again, we want to make the reviewer’s job easy and I’ve found this is one of the most powerful tools in my tool-belt.

7. Ignore Whitespace

Sometimes a simple refactor can look like a mess in the diff because you’ve re-indented or moved around chunks of code. Instead of letting the reviewer wade through the mess or placing the onus on them to realize it’s just a whitespace issue, be proactive and mention this in your description or inline comments. I often leave an inline comment in these parts of the code saying “This piece of code is best reviewed with whitespace ignored. add ?w=1to the URL to view this diff with whitespace ignored.”

8. Some Comments are Best Responded to In Real Life

After someone reviews your PR, if all goes well there’ll be a few minor comments that you agree with and you’ll happily change. But sometimes there will be comments that you don’t agree with or you think are unreasonable. When there’s disagreement about code things can get a little heated, and that’s ok. Pull Requests are democratic by nature and as such they can result in spirited debate. It’s important to have strong convictions about your own ideas but also be able to empathize and understand the ideas of those who disagree with you. If you sense heat in a comment or you feel yourself getting heated, it is best to a) Take a step back so you can evaluate the comment objectively. b) Instead of responding with another comment in the PR, use another means of communication.

If you work in the same office with the reviewer, have a face to face chat. If the reviewer is remote, a phone call or video chat works just as well. The key point here is that Github is a terrible place to have an argument. It usually just escalates the conflict instead of resolving it. And, as we all know, the best way to win an argument is to avoid it in the first place.

Conclusion

I’ve used these tips to great effect when drafting my PRs. It’s helped me ship code quicker, minimized bugs released to production and build up trust on my team. I’ve also noticed that if you open really excellent, digestible PRs others on your team will also start to do the same. I hope these tips help make your team more productive.

If you found this article helpful please click the applause button. If not, help me improve it by adding a comment below.