Code Review: Best Practices to Learn Now

When I first started as a software engineer, I dreaded code reviews. It didn’t matter how confident I was with the code, every feature I wrote required changes—and it made me nervous. But it turns out that code reviews don’t have to be something to fear. After I got over the initial hump, I realized how helpful the process is for my personal growth and how much of an opportunity it is to get insight from more experienced engineers.

And the value of code review doesn’t end there—it’s also beneficial for various team dynamics, such as team culture and mentorship. Eventually, I even started to look forward to code review, and you can too.

So what is a good code review process? And how do both the reviewers and the developers play a role to benefit the greater good? Let’s take a look.

What Exactly is a Good Code Review Process?

Code review is multi-dimensional—there’s more to it than just reviewing code. As a result, there are many benefits of a code review process.

Among those, the three most important criteria are:

1. Improve quality and consistency in the codebase: This is the main purpose of code review in general.

2. Create productive team collaboration: The code review process involves all developers, who work together effectively to iterate on solutions.

3. Ship code reasonably fast: Don’t rush code reviews, but do try to complete them as quickly and seamlessly as possible.

The Most Important Thing to Remember About Code Review

The main purpose of code reviews is to improve quality and consistency in the codebase. It is NOT an avenue for showing off or putting people down—code reviews should be a respectful dialog between peers.

That’s why the most important practice is to be respectful to one another. Think carefully about how you word your comments and responses, and do your best to understand the perspectives of others. We’re all on the same team, so we should be working with one another, not against.

Now, let’s take a look at how both the developer and the reviewer can work together to accomplish a successful code review.

If You’re the Developer…

It may seem like the code review process begins once a reviewer starts reviewing the code, but it actually starts earlier than that. Before you ask for reviews, you should do two things:

1. Review the code yourself: Make sure there’s nothing extraneous or obviously broken before asking for the time of others.

2. Provide sufficient context on the pull request (PR), so that the purpose of the code is clear: This saves time for the reviewer—instead of trying to figure out what the code wants to do, they can focus on whether it makes sense. Reviewing code is hard, so developers should strive to make the reviewer’s life as easy as possible.

Of course, the process isn’t over once reviews have been submitted. When responding to feedback, you should:

1. Clearly respond to all comments: Your response should be clear, regardless of whether you’ll make changes or not (simple acknowledgements are fine). This makes it easier for others to follow the conversation.

2. Handle the feedback constructively: Try not to take feedback personally—you should always look at the constructive criticism within the comment.

3. Try to be unbiased: It can be tough sometimes to receive feedback after putting in a lot of hard work on a PR. You may even reflexively think the reviewer is wrong. In these situations, it helps to take a step back and, to the best of your ability, reconsider the reviewer’s comments without bias.

If You’re the Reviewer…

Reviewing code is hard. It involves context switching, which can be mentally taxing. And you can’t afford to take too long in just understanding the PR, as you also have to think about and come to conclusions on the state of the code. In order to do all of that, it’s important to start on the right foot, which means…

Don’t dive head-first into the PR: You should begin by understanding the purpose of the PR (if you’re using a ticket management system, you would read the details of the corresponding ticket), as well as additional details the developer provides. It’s vital to have this context, as it will inform the rest of the review.

Although the hard part is getting through the PR and coming up with feedback, here are a few things to keep in mind while writing comments:

1. Be explicit and explain reasoning when possible: It’s helpful to clarify feedback for the developer as it can eliminate some back-and-forth.

2. Give an appropriate amount of guidance: Use your best judgment here—ultimately the developer needs to fix the PR, but there’s nothing wrong with being helpful.

3. Not every improvement is a required change: Always remember that there is no such thing as perfect code. When making comments, try to strike a balance between improving the quality of the code and progressing towards shipping the feature.

And one last thing…

Code review responses should be fast

In order for a team to move at a fast pace, code review can’t be slow. Generally, a slow code review process does not result from a slow review itself, but rather how long it takes for response (on both sides). As a general rule of thumb, it should not take more than a day for a PR to get reviews.

Code review can be stressful and challenging at times, but the payoff is worth it. A good code review process not only improves the quality of the code, but enables collaboration between developers.

And really, the principles covered in this article are not only conducive to a good code review process, but also a collaborative engineering team in general.

Hopefully you found these best practices helpful. But keep in mind that there are numerous situations that arise during code review, and this article is by no means exhaustive in covering those.

Here are a few additional code review resources that I found helpful:

• https://google.github.io/eng-practices/review/reviewer/

• https://stackoverflow.blog/2019/09/30/how-to-make-good-code-reviews-better/

• https://medium.com/palantir/code-review-best-practices-19e02780015f