The Comprehensive Code Review Checklist

A code review is a helpful tool for teams to improve code quality. Yet, there are many other benefits to reviewing code. Not to mention the reduced development cost when catching bugs early in the development lifecycle, sharing knowledge, and improving the team's estimation skills.

This blog post will explain what a code review is, why you should implement code reviews, how you can prepare for one, and how to give actionable feedback. In the last section of this article, you can find a code review checklist to use when implementing a code review process in your developer workflow.

First, let's understand what a code review is?

What is a Code Review?

A code review aims to improve the quality of the code that you want to add to your codebase. A code review refers to a systematic approach to reviewing other programmers' code for mistakes and many other quality metrics. Additionally, a code review checks if all requirements have been implemented correctly.

In most developer teams, a developer will submit a Pull Request (PR) to add code to a codebase. One or multiple team members will be assigned to review the code, check if the code meets the quality standards, and adds the necessary documentation.

However, a code review is more than just a quality check. By assigning multiple developers to a PR, you are exposing them to new code. To complete a code review, reviewers have to understand the context and scope of the PR. Therefore, code reviews are a great tool to reduce technical debt.

Moreover, a code review can be a valuable learning moment for developers. It's a great opportunity to get feedback about your code and coding style.

Why should you do code reviews?

There are many clear benefits and reasons why your team should do code reviews.

Some of these benefits have already been addressed above. It provides an excellent opportunity for developers to improve their coding skills and get valuable feedback. Also, it's a great tool to share knowledge among different team members actively. You can prevent a "single point of knowledge failure." It means that multiple people have experience or knowledge about a specific part of the codebase. It can, for instance, be useful when a particular developer is on holiday (or sick), and you need someone to review code that targets this developer's area of expertise.

A less obvious ROI metric of code reviews is reducing development costs by catching bugs early. A code review can help you find bugs that might slip undetected through testing or automated code review tools.

And lastly, code reviews help you to improve your estimation skills. Atlassian provides a good explanation.

"Estimation is a team exercise, and the team makes better estimates as product knowledge is spread across the team. As new features are added to the existing code, the original developer can provide good feedback and estimation."

So, how do you prepare for a code review?

Preparing for a code review

Before starting a code review, make sure you have all information you need to start the review. You don't want to be blocked halfway through your review because you don't have access to the information you need to complete the process.

Also, make sure you understand the context and scope of the PR. This will make it easier to review code and check its requirements. I always suggest developers try out the code and use the debugger to gain a deeper understanding of how the code works.

Image credit: Ilya Pavlov on Unsplash

How to give specific and actionable feedback?

Firstly, make sure to create a friendly atmosphere. Code reviews aren't a tool to criticize your colleagues. On the other hand, you want to create a supportive environment.

The best way to do this is to provide friendly suggestions, explain your reasoning, and give tips on improving the code. You don't want to tell the PR owner that this code is not good. Make sure to include reasoning and give tips or even snippets of code to improve the PR. The PR owner will appreciate this feedback, and it's a great chance to learn something new.

Tip: Ask questions rather than making statements. If you do this, you force the PR owner to think about their code and find a better solution themselves. In other words, you create an actionable learning opportunity for the PR owner. However, don't forget to add sufficient feedback for the PR owner to understand your question.

Code review checklist

A checklist helps you to create a structured approach to code reviews. Also, they remind you of all the quality checks you need to perform to approve code into the codebase.

You can include many specific items into your code review checklist. Here's an overview of must-have items you should always look out for.

1. Verify feature requirements

Once you have absorbed the context of the PR, it's time to verify the requirements. You want to make sure that the PR covers all requirements as described by the feature ticket. If something is missing or incorrectly implemented, you should stop the code review and ask the developer to complete the PR. You don't want to waste time reviewing the rest of the code while it might still change.

2. Code readability

Once you have verified the requirements, it's time to take a look at the readability. The main question you should ask yourself: "Is the code self-explanatory?" If you find a function that is not readable, suggest breaking up the code or reorganizing it to improve the readability for other developers.

3. Coding Style

Most development teams prefer defining a coding style guide. You can use this style guide to review the code. Again, using the same coding style will improve code readability.

4. Clear naming

Verify if function and variables are descriptive. To improve readability, you should understand what a module or class does by just looking at the function names and variables. Many developers use this approach to understand the scope and context of a new PR quickly. Therefore, developers must use clear naming.

5. Code duplication

Make sure to check for code duplication. Newer team members sometimes don't know which functions or libraries already exist. Therefore, they might create their own library while this functionality already exists. To keep your codebase clean, check for code duplication.

6. Tests

You should always check that the implemented tests cover all coding paths. Make sure to flag any missing tests to the PR owner.

7. Documentation

And lastly, a developer should update the documentation when adding a new feature to the codebase. However, don't forget to check the quality of the documentation.

Conclusion

Code reviews are a handy tool for developer teams.

Keep in mind that code reviews are for everyone in your team. Some companies mistake code reviews for a way to provide junior team members feedback from senior team members. The opposite is also true. Any developer in your team can learn, improve, and share knowledge.