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.
How to give specific and actionable feedback?
Firstly, make sure to create a friendly atmosphere. Code reviews aren't a tool to criticise 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 reorganising 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.
How to improve codebase communication?
A significant amount of code review time is spent reading and understanding code. The best way to improve your codebase communication is to add code issues using the Stepsize extension. You can create, view, and prioritise your issues and make sure all members of the team have access to this valuable code context.
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.
P.S. Check out our latest industry report on How Codebase Health Impacts Engineering Hiring and Retention where we gathered insights from 200+ Engineers 🙌
Top comments (2)
I doubt that "Verify feature requirements ✔️" should be part of the code review. This is something to be verified by the demo to the product owner, but of course your workflow may differ.
"Coding Style 💅" should be automated as much as possible, in practice, with the right tools, this can be done by a machine. If you still discuss about code style in CRs you are not automating enough.
" Tests ✅ You should always check that the implemented tests cover all coding paths. Make sure to flag any missing tests to the PR owner." Again that is a job for a machine - automate this away, you'll have enough work with checking that the tests make sense and testing the right thing, the right way.
Thank you for this very great quality post. 🤜🏼🤛🏼