Subtle Art of Code Reviews

Code reviews are a necessary step in ensuring quality work. Here are some tips to get the most out of this process.

Originally Published at: Subtle Art of Code Reviews

The dynamics of modern work culture, especially during a pandemic, have changed. Workplaces that were once offices are now confined to homes. With this shift comes new challenges and complications in terms of collaboration. One important aspect of collaboration on code specifically involves code reviews.

So, you’ve pushed some code and asked your peers to review it so they can make sure you haven’t made any blunders. Because your coffee hasn’t kicked in that morning or you were having an off day, making mistakes is entirely possible. That’s why an extra set of eyes in the form of peer reviews is the single biggest thing that can help you improve your code.

The Internet is filled with reasons why code reviews are important, but there are some nuances that need more attention, especially for teams working remotely.

That means the amount of advice out there makes it more difficult to actually do it right. So, the question you might be asking yourself is, “What really is the subtle art of code reviews if not just common best practices?”

Before diving into this topic, let’s quickly go through the phases of code reviews. In general, there are three main phases for the reviewer:

1. Approve pull request
This one is fairly straightforward. If you feel good about the code, go ahead and give your peer the green light.

2. Change request
If you think there’s something in the code that might create a problem, ask your peer to address that change and request to review the code again when they are done with resolving the issue. Be mindful of requesting changes and do it when you actually spot an issue and it’s something that a reviewee can take care of.

3. Comment
Unless your brain is falling apart between approving the code or asking for changes, go with comment mode. One of the main challenges being on the receiving end of code reviews is taking criticism, so make sure you do not do it too often. Also keep in mind that you are delaying the code review by essentially dividing the review into two phases, as the reviewee still has to wait for approval or change requests.

Now that we understand the basics of code reviews, here’s how you can turn those simple steps into a work of art.

Working efficiently in a remote culture

Friction is the by-product of remote work culture: Colleagues are not in the same room anymore. Seeking help and advice on your code on the fly isn’t as convenient as it used to be.

How you lower the friction shows how good you are at collaborating with the team.

Geographical distance can add more challenges to the reviewing process, even more so if peers are working in different time zones. Then it’s a different ball game altogether.

One of the best ways to be helpful is by being specific and mindful during the review.

For example, say a similar problem or use case exists in the codebase that a reviewee isn’t aware of. Pointing them to the exact file or typing out that snippet of code if you can will help them a lot. Putting that snippet out there during peer review doesn’t mean you’re giving away company secrets, so it’s totally OK to do that.

If you receive reviews with the exact snippets of code you need on the review, even with a 12-hour time zone difference you can save a lot of time and effort.

Avoiding extra work

It’s completely OK to go ahead and just approve the code review—you don’t have to try to find issues in each and every pull request.

You might be asking, “Isn’t that the whole point of reviewing the code? To find issues?” It is, but don’t overdo it by looking for issues that don’t exist.

It’s not a competition

You might be naturally good at noticing issues, but that doesn’t mean you have to notice every little detail all the time. Qualitative review is more important than quantitative effort.

Giving praise only when it’s warranted

Don’t overly praise the reviewee just so you can criticize a piece of code—just be yourself. It’s okay if there’s an issue within the code and you have pointed it out; the goal is not to be rude about it.

Another reason why you shouldn’t call out each and every code review as “amazing” is because your peers might not know when you actually feel good about the code.

You don’t have to bear all the burden

We are not living in the ‘90s anymore—we have modern integrated development environments (IDEs) to back us up. Save the reviewer some time by setting up tools correctly.

Something almost everyone does is make linting mistakes. A simple linter could fix the error, saving your reviewers time.

For example, if you are getting too many “you have missed the brackets” or “have unused imports in a file” messages, then it’s time to enable linters by configuring plugins and extensions within your IDE. Better yet, do it within the code to help find issues before putting it in front of the reviewer.

Agreeing to disagree (and moving on)

At times the reviewer and reviewee may end up arguing over a potential issue that may never even occur. In this instance, it might be better to let the situation alone and agree to disagree.

Lengthy discussion around theoreticals sometimes creates delays in delivering a feature, or it could end up making the task more complex than it needs to be.

Mindful behaviors

Here are a couple of things you should consider before assigning PRs to peers:

• Do not tag all reviewers on each and every pull request.
• Add at minimum two and at most three reviewers per PR unless there’s an absolute need for adding more peers.
• Give responsibility by assigning it directly to one of your peers.
• Keep the pull request short if you can.

Being the change you want to see

Have you ever been at a point when you are swamped with work and suddenly get tagged on a pull request, and you can’t decide what to prioritize?

Code reviews often get assigned to specific people. If you are one of those people who isn’t added to that list, but you have the context and time to review it while others are busy, just go ahead and do it. You’ll be helping out your swamped teammates while developing a culture of sharing the burden.

Context is king

Providing context is important when creating a pull request. You, as the author of the code, might know exactly what’s going on, but the reviewer will need some more description to help them navigate through the code.

For instance, if someone recently joined the team, they likely will have no idea what you wrote. Giving them some context by either writing a description, providing steps to reproduce if it’s a bug, or adding a video attachment will go a long way. The goal is to make sure that when someone is reviewing your code they don’t have to figure out what the code was for or, at worst, get you on call to ask what’s going on.

Final thoughts

Whether you are a reviewer or the reviewee, you should be mindful of how you can make sure the quality of code isn’t compromised and how you can make it painless for the next person in the process.