Code review is one of the most powerful tools in a developer team’s arsenal when building software. However, it sometimes gets neglected or becomes used in ways that cause more harm than good. But when done right, a code review can help your team share knowledge, mentor junior developers, and improve the skills of more advanced developers all at once.
Consider this: When reviewing code, team members become familiar with parts of the code that they would otherwise never learn about. That’s why code reviews are so important for spreading product knowledge within the team. By engaging everyone in reviewing code, you can be sure that there is always a person you can consult about a part of the code - even if the author of that part isn’t present.
When reviewing code, developers usually become more attuned to code quality standards when they know that others will be reviewing their work once it gets into a pull request. You can probably already tell code reviews streamline the development process and collaboration between developers.
So, what exactly is a good code review and how to achieve the idea? Read this article to learn the ins and outs of code review best practices from our team at Codete.
Table of contents:
Code review - how to do it well
Every development team out there strives to run good code reviews. There are a few common and easy-to-follow industry best practices that you can get started with. They open the doors to high quality and helpful reviews in the long run.
But when code reviews can always get better. Great code reviews are the ones that actually inspire engineers to keep improving how they perform code reviews. They examine the code changed in the context of the entire codebase, the particular situation, and the person requesting the review. Reviews like that can easily adjust their approach on the basis of the context.
The goal isn’t only a high-quality review but also helping teams to become more productive.
Code review best practices
1. Make sure to cover these areas in your code review
High-quality code reviews examine not only to change itself but also how that change fits into the entire codebase. They look at the clarity of the title and description as well as the “why” behind making the change. A good code review also explores the correctness of the code, functionality changes, and test coverage - all to confirm that they follow the best practices and coding guidelines of the team.
Then, a review points out improvements that need to be made and fixes to problems such as unclear names, hard-to-understand code, or unhandled edge cases. If too many changes end up crammed into a single review, it’s best to keep the change to a single purpose or break it into several more focused parts.
But for a code review to make a real difference, it needs to look at the changes in the context of the larger system, all the while checking that the changes are easy to maintain. Reviewers might ask questions about why the change is necessary and how it impacts other parts of the system.
It’s smart to look into obstructions introduced by the change and check how they match the existing software architecture. Problems like overly complex logic, structure, duplications, and others will all be noted in such a review.
2. Achieve the right tone for your review
The tone of your code review will impact the morale of the developer team. If you carry out a review with a harsh tone, you might end up creating a hostile environment with problems like microaggression and lack of trust. The overly opinionated language will make people defensive and might spark heated discussions that aren’t really productive.
A professional and positive tone, on the other hand, will create a more inclusive environment where developers are encouraged to share constructive feedback. As a result, the review will trigger healthy and lively discussions that are incredibly productive to the team.
So instead of making opinionated statements, a good code review:
- asks open-ended questions,
- offers alternatives and possible workarounds,
- doesn’t give teams solutions,
- doesn’t insist on solving problems in a particular way.
Good code reviews assume that the reviewer might be missing an element or knowledge about the context - instead of forcing a correction, they ask for clarification.
In our experience, the best code reviews also come with a degree of empathy. They understand that the person writing code spent a lot of time and effort on it. They’re unassuming and simply kind.
3. Build a process for requesting and approving changes
Once the reviewer completes a review, they can mark it as approved, block the review with a change request, or leave it as “not yet approved” without leaving any specific status.
The way in which reviewers use these methods to approve and request change statuses is an indication of the review’s quality as well. For example, a good code review won’t approve of any changes when there are still any open-ended questions left to be answered.
They also clarify which comments or questions are non-blocking and mark them distinctively. And when approving a change, reviewers need to be explicit about it - for example, by adding a thumbs up comment. That’s how you avoid costly and time-consuming communication between team members.
4. Prepare code reviews for new team members
Starting out a new job with a new team can be overwhelming. The codebase is brand new, the style of programming might be different, and people will review your code in a completely different way.
So, here’s the question:
Should the code review be gentler for new hires to get them used to the new environment or keep the bar just as high?
The best approach is to use the same level for everyone, regardless of their job title or when they joined a company. Still, it’s smart to pay extra attention to making the few first reviews for new joiners a nice experience.
Start with being empathetic to the fact that the person might not be aware of all the coding guidelines or familiar with other parts of code. Such reviews put some extra effort into explaining alternative approaches and point the person to the right guidelines. The tone should always be positive and encouraging, basically welcoming the new person to the team.
5. Ace cross-office or cross-time zone reviews
Code reviews can become challenging when the reviewers are located in the same location 0, but they get especially problematic if reviewers and authors are located in different time zones.
First of all, it’s important that reviews account for the time zone difference whenever they can. The idea is to review the code in the overlapping working hours between the two offices. If a review has many comments, the reviewer can offer to have a direct conversation or video call to talk over the changes.
If you notice that your code reviews keep on encountering challenges related directly to time zone issues, you need to start looking for a systemic solution.
For example, if a team from Asia frequently triggers code reviews from the Europe-based owner of the service, you need to ask yourself:
- Why are those changes happening so often?
- Are they down to the right database, or should another system be changed?
- What about the frequency of changes? Should it stay the same or go down in time?
- Is it possible to address such cross-office dependencies in any way?
The solutions to these issues aren’t going to be easy and might involve refactoring, creating your own services, or improving your tooling. But it’s all worth it - solving such dependencies will make the life of your developers much easier.
6. Put a limit on the review sessions
Code reviews can’t be limitless or rushed. The idea of introducing limits is to catch mistakes when people can truly focus, not at times when they’re in a hurry and just want to get into or out of the office.
Many software developers can get through some 300 to 500 lines of code within an hour. According to statistics, after the first 60 minutes, their effectiveness drops significantly (and then drops even further after 90 minutes).
That’s why it’s essential to limit review sessions to 300-500 lines of code.
7. Create metrics and goals for code review
Once you have set up a solid process, you’re on the way to success. But you also need to find a way to measure its success. This is where metrics come in. By using external and internal metrics, you can decide whether the code review needs revising or it’s going in the right direction. Note that code review should always be a modifiable process that matches the needs of your team, product, and company.
The external metrics you can use here are, for example, defects found before releases or defects reported by users. Internal metrics can be inspection rate or defect rate. Naturally, you shouldn’t ever use the results to blame anyone but rather use them to assess the process and ensure that it’s as efficient as you want it to be.
8. Use automation to your advantage
Many teams use automated tools for making code reviews primarily because they work really well for implementing stylistic conformity. Developers don’t have to put in the extra effort into following the outline of a code review perfectly on each and every line of code.
When it comes to formatting and style, automation is your best friend. Everything will go smoother without wasting the precious time of your developers.
9. Make sure to annotate code before the code review
By annotating a piece of code before sending it out to be reviewed, you will be accelerating the process significantly. Self-describing code is helpful - especially for the more complex part of the code. The reviewer can spend less time figuring out what the code actually does.
Thanks to proper explanations, you can also avoid potential issues before they even happen or at least streamline the discussion on them. As a result, your code review will be faster and more efficient.
10. Include everyone in the code review
Make sure to involve every single developer in the code review process. Junior developers can learn a lot from code reviews. The code review spreads product knowledge to the entire team. And seeing reviews from both sides helps everyone to become more comfortable with the process. Of course, it’s helpful to have a senior developer review certain pieces of the code but make sure to include everyone in the process.
Using our code review best practices = better code quality
Code reviews can work wonders in a team of developers, but they require some time and effort to set them up. Your team needs to make sure that the review of the change itself is combined with the right tone and lack of nitpicking. Regardless of who requested the review, the bar should remain consistent. And the code review process should support teams working across different time zones.
It’s best to continue improving the details of your code review and looking at the changes requested from the higher level. Teams that invest in tooling and process improvement are the ones that benefit most from code reviews.
What is your experience in code reviews? Are you using any tools to support your team’s code review process? Give us a shoutout in the comments! We look forward to hearing more about industry best practices for code reviews implemented in your companies.
