The Principles of Code Review

When you’re dealing with code reviews, and making them a cornerstone of the development process (as you should), best practices matter. We will concede, however, that the best practices in this field aren’t yet set in stone. Perhaps they never will be. Reviewers are different, and we are always careful to encourage them to experiment and figure out what works best for them. Our goal at Reviewpad is to create the tools that will allow every reviewer to find their footing and engage with reviews in the way that works best for them. We do believe, however, that there are principles that are key. Today, we tell you about them.

1. Be thorough

Some people will prefer to have a checklist. Others, more experienced, will rather not. This is up to you. Some will prefer to time their reviews. Others will prefer to set a hard-limit in terms of either time or lines of code to know when to stop. All of this is debatable, and you should figure out what works for you. What truly matters is that you do a thorough review. It’s unacceptable to review the first half of the code with care and then speed through the rest to meet some sort of arbitrary time-limit. If the time-limit is wrong, fix it. If the limit is necessary, then break up the review into smaller pieces.

Do not half-ass it.

2. Make your feedback actionable

There are many styles of feedback, and it’s hard to tell you what better suits your team and the project you’re working on, but it’s very important to keep things precise. Kindness is key - personal issues should be kept away from your reviews. Feedback shouldn’t just be positive/negative, it should be actionable. What needs changing, and why. What doesn’t work, and why it matters. When leaving a comment, make sure whoever reads it understands what you think should happen next (NB: “fix it” doesn’t count).

3. Make sure you understand every change

If you’re not sure what something does, don’t just let it go. Even if the author of the code is a more experienced developer and you trust them. Everyone makes mistakes, regardless of seniority, and it’s your job to catch them. You can’t do that if you don’t fully understand what the code does.

Is it too complicated?

No worries. Just ask for an explanation or a simplified version. Code should be readable, and making it so is an important part of code reviews. Don’t shy away from saying you don’t get something.

4. Don’t approve code that isn’t ready

This one seems like something that shouldn’t need to be said, yet it does. Developers will often approve code that doesn’t have obvious mistakes but could… you know… maybe… be improved…?

If you feel like the code isn’t ready to ship to the client, then you shouldn’t approve it. Of course, some exceptions apply, if you are in a crunch and a new feature needs to be tested, etc. but as a general rule? Only approve code that works.

5. Always raise standards

Are you keeping to your team’s standards? Do they follow a checklist that you aren’t keeping to? How about documenting the code? Making sure everything has the required test coverage? Respecting the same coding conventions?

You are? Brilliant! Time to raise those standards.

We believe in continuous improvement, and that’s one of the keys of code reviews. Don’t ever find a comfort zone. If you feel like you are just coasting with your reviews, then odds are you will probably start making mistakes out of complacency. Don’t allow that to happen.

6. Assume nothing

Senior devs make mistakes. Junior devs create wonderful code. So why would you not be every bit as attentive while reviewing a senior’s code? Why would you expect messy code from a junior? Never take anything for granted. Go into every review with a clear head and act like you had no prior expectations.

Make sure your comments also reflect this. Feedback in code reviews is no place to air out frustrations with someone who has made the same mistake three times. Leave actionable and precise feedback once again and figure out HR issues later.

7. Be a team member!

Code reviews are the perfect place to set ego aside and ignore whether the code was written by your friend or the person you personally like the least on the team. They are the place to put aside your own preferences about what kind of code is “techie” or “fun”. They are the place to worry about one thing, and one thing only: the success of the project.

And the project belongs to no single individual. The whole team is working on it, and the whole team should feel like they own it. The goal is to create code that is as functional and maintainable as possible. Everything else doesn’t matter, whether they are pet peeves or history.

8. Learn!

This one is the simplest of all.

Even if you are a rockstar developer, there’s a lot of knowledge being exchanged in code reviews. Even when doing them. Whenever you’re going through everyone else’s code, always be mindful of this. Maybe that mistake you were about to fix wasn’t a mistake at all.

Maybe it was just a different way of doing things. Maybe one that’s actually better.

Never stop learning.

Did you enjoy this article? We are building the tools to help people put all of these principles in practice by making code reviews as easy and painless as possible. You can try it out for free right here.