Effective code reviews: how to improve your team's code quality

Code review is one of the crucial processes in development to ensure the dissemination of knowledge and best practices across the team. Giving and receiving feedback on your code or Merge Requests - MRs (or Pull Requests - PRs, depending on the platform used) is an essential part of ensuring the quality of implementations and of the growth of both the reviewer and the one being reviewed.

The main advantages of a well-done code review are:

• • Sharing knowledge about the codebase and the business;
• • Jointly identifying whether it's the best solution or whether there's something to improve;
• • Proposing different approaches to the same problem;
• • Ensuring the code follows architectural and language standards;
• • Finding potential bugs and vulnerabilities;
• • Growing the knowledge of everyone who participates;

Phases of code review

A code review can be divided into two phases.

Phase 1: Quick review

In this first phase, going through the diff (code difference), you normally look for the following:

• • Obvious errors: typos, bad names, overly large function definitions;
• • Commented-out code: commented-out code should be deleted;
• • Violations of architecture and coding standards that linters don't catch;
• • Tests: if there are any (I strongly advise having them — they ensure quality and will save work in the future), validate that the tests were written and that they run;

Ideally, before opening the MR (Merge Request), the developer should do this same review; that way few problems of this kind should reach the code review. Also, depending on the amount of changes, a careless reviewer will do a review of the "terms of service": scroll, scroll, scroll, accept.

Another important point is to use tools in your favor. A Linter and the use of EditorConfig can save time so you can focus on what really matters.

Phase 2: Context review

This review is deeper and will possibly take considerably more time, since it's about getting to know the context of the application and the change, and validating the changes submitted in your MR. Many projects simply force this review to be skipped precisely because it takes longer; however, it is the one that can ensure users won't suffer from those bugs.

In this phase, you look for items such as:

• • The best ways to use the frameworks/libraries;
• • Implementations or refactorings that improve readability, understanding, and maintainability;
• • Can you really understand what the code is doing? If the code is hard to understand, that should be fixed/improved.
• • Validate the MR's changes against the business rules or the context of the change;

It's worth remembering that there is a correlation between the amount of changes, the quality of the review, and the number of bugs. The more changes or the bigger the implementation in an MR, the harder it will be for the reviewer to understand the changes and ensure more quality, and the number of unnoticed bugs may also be higher.

If you have trouble understanding the context, or genuinely have no knowledge about it, the reviewer should reach out to the code's author to explain each of the changes.

Ways to make your code review more efficient

1. Review only what makes sense

Focus on reviewing what will really make a difference. Automate as much as you can, and use tools in your favor.

2. Everyone on the team should do reviews

The responsibility of reviewing shouldn't fall only on the most senior. Each developer has their own view of the code, and that can bring better approaches to solving the problem.

3. Evaluate the code, not the person

The feedback received when evaluating code should be understood as a way to improve your knowledge and coding standards.

4. Avoid very large merge requests

Agree with the team that MRs should be small. The recommended size is under 300 changed lines. If it's larger than that, split it into smaller MRs.

5. Gather context if it's missing

If information is missing, look for that information; it's important to avoid misunderstandings about the code and the business rules.

6. Start at a high level

Do the review from the top down. Avoid commenting on small changes like styles and indentation until the bigger issues, if any, have been addressed. That way, the author can focus on what's most important and, in some cases, the minor problems disappear along with them.

7. Provide justification and code examples

If you disagree with some part of the code, it's important to provide justification and examples of how to do it the best way. This is much more useful to the other developer than just writing "refactor" in the comment.

8. Discuss the code whenever possible

Asking the author questions and thinking about improvements together is the best way to think through the problems and arrive at the best ways to code.

9. Empathy

Most important of all, remember there's a person at the other end of your evaluation. Providing feedback in a helpful and constructive way will make the team grow.

Conclusion

After a while reviewing code, I believe peer code review is the best way for you and your colleague to improve the code and your skills — not only technical ones. Besides that, it's clear that every minute spent on a code review will pay back ten times over in the future, ensuring standardization, more quality, and keeping bugs from reaching the customer or user.

A good suggestion is to create a coding standards document and a code review checklist for the team and use it as a requirement for the Definition of Done. Besides that, reviewing code shouldn't be only part of the development process, but a culture — part of software quality assurance.