How to do a Code Review: The Ultimate Guide

The importance of code review is being recognized by many development teams, and it’s often difficult to do it right. This guide gives you complete checklists to ensure that both the submitter and reviewer are not missing important points:

• for the submitter, it provides all information you need to make sure your code review is ready.
• for the reviewer, it gives a checklist of the areas to cover before approving the code.

What is a code review?

A code review is a process of checking a code change before merging it into the main branch of your repository. The primary objective of the code review is to ensure the code changes do not introduce any defects, vulnerabilities, or regressions. In short: merging this code in production is safe and will bring value to users.

There are also secondary benefits to doing code reviews:

• learning: sending code reviews to new hires help them understand the code, its context, and the coding standards being used. Developers can ask questions about the code and learn from the answers.
• team cohesion: sharing code reviews helps communicate with team members and ensures that any problems (even minimal) are raised by team members.
• testing and regression finding: code being reviewed can be automatically tested and analyzed, finding potential errors automatically before merging

Code Review: Submitter Checklist

If you are sending a code review on GitHub, GitLab or Bitbucket (or using any other Git hosting service), you can read our best code review practices for Git. These best practices help you prepare your pull request and send your code review.

Before you send your code for review, make sure you do not waste reviewers' time. Your code reviews should be clean and have all the information to be approved. Instead of waiting for questions from the reviewers, be proactive and add all the information in the initial review.

There is the checklist I usually use:

• Cleanliness: did you remove all debugging artifacts (e.g. use of printf, println and other console.log)?
• Testing: do you have enough tests in place to exercise the happy and error code paths?
• Code Hygiene: does your code have duplicates? If yes, can you refactor the code to put all duplicate code into a function?
• Information: Did you fill the code review description appropriately? Did you document the different tests you made to show the reviewers you tested the code? For example, add the output or your tests in the code review description or screenshot of what you tested if you do a UI.
• Documentation: Are documentation changes required? If yes, are they made?
• Follow-up tasks: Are there any follow-up tasks before or after this code is deployed?

Generally, before sending the code for review, I make sure the description contains at least four sections:

• Problem: description of the problem I am trying to solve.
• Solution: what is my solution, why did I choose this approach, and what are its benefits and limitations.
• Testing: explains what level of testing has been done (unit testing, integration, etc) and attaches the proof that the tests passed. In the case of unit testing, I put the output that shows that all tests passed. In the case of UI development, I attach a screenshot of the application with the changes.
• Other considerations: any link to related documentation or follow-up ticket

There is an example of one code review that follows this template.

These four sections generally provide all the information required to proceed with the review. If there is any additional information that may be required, I add them in the “other considerations” section.

Code Review: Reviewer Checklist

Reviewing code might look easier than sending a code review. After all, if anything is wrong, this is the fault of the submitter and not the reviewer, no?

Reviewing code is a serious responsibility and this is the duty of the reviewer to ensure the code will not cause any issue in production. As a reviewer, you need to also follow a checklist to ensure that the code does not have any issues.

• Correctness: does the code correctly implement a solution to the problem?
• Safety: are all error cases correctly handled?
• Evidence: does the code review provide enough evidence that the code is correct (unit testing, proof that tests were done, etc)?
• Follow-up work: does this code change require any follow-up tasks (such as database updates, configuration, or feature flags changes)? If yes, are these tasks in the backlog?
• Regression: may this code introduce a regression that may impact the service users? Should more testing be required?
• Documentation: Should documentation or runbook be updated? If yes, are they updated, and if not, is it captured in a follow-up task?

This checklist is quite extensive and was enough for me to cover my needs while working at large technology companies. However, depending on your domain and the type of services you are working on, you may want to add more steps. For example, when working on machine-learning services, one step would ensure that the model is always performing better than before.

Wrapping Up

A code review is a process in which programmers examine source code to identify possible errors. It’s a way for programmers to find problems and improve the security of the code before merging the changes in the main branch. In this article, we showed the importance of the code review process for both the submitter and the reviewer. And we gave a checklist to follow to ensure that neither the developer or the reviewer has a blind spot and misses any potential issue.

If you want to speed up your code review process, you can integrate Codiga into your workflow today. Our Automated Code Reviews tool finds issues in your code faster. It accelerates your code reviews. And gives you more confidence that the code is secure, safe, and follows best coding practices.

Finally, if you are interested to learn more about code reviews and the science around them, we recommend the Software Engineering Podcast from Michaela Greiler.