5 Best Practices for Code Reviews

Code reviews are a great way to keep your code base nice and tidy. They also help to foster knowledge sharing between your developers.

For best results in practice, we have collected 5 code review best practices for a productive approach to this important part of software development:

1. Keep changes small & focused
2. Help your reviewer: Add context
3. Leverage automation
4. Be objective, constructive and helpful. Ask questions.
5. Take your time
6. Bonus tip: Be your own reviewer

1. Keep changes small & focused

It's challenging to review large chunks of changes adequately. More complex changes have a greater chance of introducing bugs and make it harder for the reviewer to truly understand each alteration. Therefore, it's more effective to keep changes small, ideally focusing on one feature or bug fix per review.

Of course, this isn't always that easy. Even a single large feature may require many changes for the code to at least compile. In fact, making sense of a large changeset is one of the main reasons Codelantis exists as a tool!

2. Help your reviewer: Add context

In order for a reviewer to make meaningful suggestions, they need to understand why changes are being made. Providing context and clearly explaining the purpose of a code change can lead to more useful feedback.

Did you know? The early way of reviewing code involved printing the code on paper and then discussing it in a group meeting. (Source)

3. Leverage automation

There is a simple rule regarding automated tools and code reviews:

"Anything that can be checked using tools should indeed be handled with them. Humans should focus on tasks where they excel."

Modern code quality tools like Teamscale can help flag issues such as code style violations, potential bugs, or performance issues. For a human, it makes zero sense to act as a linter (let alone, it isn't fun!), so no engineer should have to write review comments about things that can be checked automatically.

Whith aspects like code style and coding conventions taking care of, reviewers can focus on the architecture, understandability, reasoning, and design aspects of the code. Plus, it also shares the knowledge about that particular part of the code base.

4. Be objective, constructive and helpful.

A code review is a vehicle for learning and improvement. Reviewers should present feedback in a positive light, highlighting the aspects that require modification rather than directly criticizing the author's code. A good way to do this is by simply asking questions:

Don't ❌

• "This line is useless"
• "You copy-pasted this code. This is a bad practice"
• "This code is a mess, it's super complicated!"

Do ✅

• "Do we really need this assertion? "
• "I think this is similar to class X. Can we consolidate this into a shared method?"
• "This method is over 150 lines long, and I'm having trouble understanding it. Can we refactor it?"

5. Take your time

Source: CommitStrip

A rushed code review is a waste of everyone's time. A helpful review requires dedication and thoughtfulness. Sure, the final merge into the release branch is the primary goal. But over the long run, being up-to-date with the inner workings of your code base is crucial for the project's success, too.

So take your time to examine the changes with more than just a quick glance. And for larger reviews, The person who implemented the changes will be thanking you. And maybe your future self, too, when you work on that area of your code base.

6. Bonus tip: Be your own reviewer

Would you publish a blog post without proof-reading it at least once? Probably not!

Similarly, it's definitely a good idea to be your own first reviewer. Put yourself in the shoes of the person you will be reviewing your code.

Questions you could ask yourself are, for example:

• Is every change (still) necessary and understandable?
• Can you help your reviewer by explaining why you changed something? (see #2)
• Do variables, methods, and classes have self-explanatory names?
• Can you write a test for your change?
• and so on...

Thanks to yelmorabit-96 and the smart people at Reddit for bringing this up!

Conclusion: Quality Code with Code Review Best Practices

Code reviews, when done right, are a powerful method to maintain the health of a project's codebase, foster continuous learning, and create a unified coding style among the team. Following these code review best practices will likely increase the effectiveness of the process, which ultimately leads to a more stable, maintainable, and high-quality product.

Remember that code reviews are an ongoing learning process. They're an opportunity for the entire team to learn, adapt, and constantly improve.

Thanks for reading!