Mastering code reviews – a comprehensive guide

The importance of code reviews

Code reviews are essential for maintaining high code quality, which is one of the most crucial things for every developer. They identify potential issues early on, enhance code readability, and ensure compliance with coding standards.

Additionally, by involving multiple reviewers, developers can receive valuable feedback and suggestions for improvement. This makes it a perfect opportunity to learn from each other (the reviewer and the code author).

Why does the optimal process for code review matter?

The primary goal of code reviews is to complete them as fast as possible. This responsibility lies not only on the reviewer but also on the code author, team or project leader, and project manager. It is a compound effort.

Moreover, as we mentioned, responsibility. Try to share the overall responsibility for changes made in the code with the entire team. Why? It is simple—even a small change in just one line of code can significantly impact the whole application. It is always better when the entire team is responsible for something; this way, the chances of delivering the best code quality increase.

Avoid long code reviews, as other team members often dislike them. They may also incur high costs and lead to the adoption of bad practices. If your team needs help conducting quick code reviews, reconsider the process and rules surrounding them.

Establishing a code review process

In a previous paragraph, we established why it is crucial to have an optimal process for your code reviews. Now, we will go through how to create one, step by step.

Set and communicate responsibility

Make sure to clearly communicate the individuals responsible for conducting the reviews. You can implement two different approaches:

• When creating a merge request, always assign specific reviewers. This ensures they are notified and aware of their responsibility to conduct the review.
• Establish a rule where anyone who sees a merge request automatically takes on the responsibility of conducting a review. If the process is manageable and you have a motivated team that will adhere to this rule, it can significantly reduce the time needed for reviews.

Code review in your project management tool

When preparing the whole process for code reviews, allocating a special column in project management tools like Jira or any Kanban board used by your team is crucial. This way, you will shift the perspective from code review to an integral part of the process, and, at the same time, it will become an investment that yields benefits.

Define the time for code reviews

Set strict times for code reviews to avoid merge requests waiting for weeks due to other priorities. Here are some possible approaches:

1. Conduct code reviews in the morning before starting your tasks. This approach allows for a fresh mindset and uninterrupted work for the rest of the day.
2. Perform reviews in the afternoon after completing your tasks. While it doesn't interrupt work, people may be tired at the end of the day and might miss some bugs. Additionally, they may be in a hurry and have other commitments right after work.
3. Incorporate reviews in between each task. This can serve as a break between tasks and allow multiple reviews in a single day without blocking progress.
4. Combine all three approaches - this is a great idea for larger teams where reviews are not assigned to specific individuals. It allows for frequent reviews that do not hinder the overall process.

Include every developer in the code reviews

Ensure that every developer on the team participates in code reviews, regardless of their level of seniority. Senior developers should review code to identify both minor and major mistakes, as well as to guide others. Junior developers should review the code to practice understanding the code they did not write, learn from it, and gain exposure to good practices and patterns.

Test only approved changes

Remember that when approaching the testing phase, you should test only tasks that have passed a full code review. Testing them before other developers have reviewed them may be a waste of time, as often fixes need to be made.

Optionally, you can also consider the following tips:

Consider setting a minimum of two reviewers

When you have a large project with significant responsibility (e.g., a design system used by hundreds of people), setting a minimum of two reviewers is a good idea. One pair of eyes might not catch every suspicious thing in the code, so having another person check is beneficial. Additionally, one reviewer may be familiar with the changed component and can identify risky changes. At the same time, the other, who has never seen it before, can provide a fresh perspective and propose better solutions.

As a tech lead, try to participate in every code review

If possible, a project tech lead should be among the people who need to conduct a code review for every change in the project. Although it may take a lot of time, it ensures consistent code throughout the application and informs the lead of every minor change. This practice is often beneficial, as the lead has complete control over the project and can better address user, client, or business questions.

Filter out the merge request list

It might be helpful for team members to create a bookmark in their browser with a list of merge requests with saved search filters. This search should return only the merge requests that meet the following criteria:

1. The team members still need to approve them.
2. The given team member does not write them.
3. They are not in draft status.

This way, team members will not miss any new or older merge requests waiting for review or re-review.

How to conduct effective code reviews

Once the code review process has been established, it is time to focus on conducting the review as effectively as possible. To help you prepare for the review, we want to share with you some of our best practices:

1. Make sure you understand the context of the changes. Check the merge request description or the task description first. If you have any doubts, don't hesitate to ask the author.
2. If the merge request is extensive, first focus on the code's main functionality. If you catch any significant mistakes here, checking the rest of the code might not make sense, as after the fixes are added, the rest of the code might change as well.
3. Constructively frame your feedback using language that encourages collaboration rather than criticism. Instead of directly pointing out mistakes with phrases like "You made a mistake here," opt for a more neutral tone by saying, "Here is a mistake".
4. Instead of solely identifying problems, providing solutions or suggesting alternative approaches is also helpful. This enables the author to understand better how to address the issues raised in the review. Remember, though, that it is not your responsibility to come up with a suggestion if you don't have one immediately.
5. Provide sufficient detail in your feedback, but avoid overwhelming the author with excessive comments. Be concise and to the point.
6. While catching bugs and potential problems is crucial, it is also important to consider the bigger picture and provide feedback on the overall code structure and design. Your suggestions can be a great starting point for brainstorming and initiating global changes.
7. Feel free to ask questions if something needs to be clarified or if you need more information. Encourage the author to provide additional context or explanations where necessary.
8. If the code review has time-sensitive aspects, please communicate that. Consider the urgency of the changes and prioritise feedback accordingly.
9. Suppose your comment is about a change that is not mandatory from your point of view. In that case, it's just a suggestion or pertains to a global pattern or structural change that should not be made in the current merge request but in a separate one; be sure to emphasise it. You can label your comment as optional, e.g. "Optional: consider moving this function to a separate file".

Automate wherever possible

Numerous tools can expedite code reviews and automate various checks, including:

1. Linters and Static Analysis Tools, e.g. ESLint and SonarQube. These tools automatically analyse code for potential syntax errors, style violations, and security vulnerabilities. You can customise their rules to match your project's requirements and coding standards.
2. A Continuous Integration Pipeline with automated code review steps. This pipeline should execute automated tests, linters, and static analysis tools whenever changes are pushed to the repository. Any identified issues should prevent the code from merging until they're resolved.
3. Code Formatting Tools like Prettier automatically format code according to your project's style guidelines.

How can developers help in the code review process?

Undoubtedly, developers are crucial to every code review process, but how can they help you? Here, we prepared a couple more tips regarding the role of developers in your reviews.

Let's start with the obvious ones – developers should communicate the context of their changes. This can be done by providing a link to a well-described task or explaining what has changed in the merge request description. This will help everyone to understand the problem and not make similar ones in the future. Moreover, actively engage with reviewers' feedback to ensure a positive code review process. Adopting a collaborative attitude is key.

Going further, divide your large tasks into small ones. It truly makes your review more effective and easier. You can probably recall a situation where a merge request with only ten lines of code received ten comments, while the one with 100 files changed received none. By dividing your tasks, you ensure that everything will be done evenly and everyone will remember their tasks.

Talking about making the code review easier, remember about writing a code that is easy to read. Switching from writing cryptic code that is understandable only to you to writing readable, verbose code – this way, you can save your reviewers quite a few minutes.

Next, divide more extensive code into smaller parts, each with a proper name and comment. This will make the code much easier to read and prevent the loss of context for each specific part.

We all know how crucial documentation is, right? The same goes for the code review process. Be comprehensive when providing documentation, especially for complex features or changes. It should include information about the purpose of the code, how it is used, and any considerations for future modifications.

Finally, before submitting your code for review, always perform a self-review. This can help catch and address potential issues before the formal review process. Even a quick look might catch any bugs or some console.logs.

Developers' response to receiving feedback

It is natural for the code's author to consider their code as the best possible solution. But, sometimes, when others look at your code, they might not think the same way. It is also essential to prepare yourself for such a situation.

As a feedback recipient, remember that code reviews are primarily about learning from each other and growing as a team. Don't take it as criticism or a personal attack. The reviewer's job is to catch as many things as possible, and even if the review seems too strict, it will usually be beneficial in the long term. Never respond in anger or frustration just because someone is following the code rules or asking questions about your code. Respond calmly. If you disagree with a suggestion, try explaining your viewpoint. Avoid responding with a simple "no."

Everyone should also remember that they may be wrong about either the solution implemented in the code or the solution suggested in the review. If there is a problem with deciding who is right, feel free to include more teammates to help solve the issue, for example, by voting. Treat it as a learning opportunity and a brainstorming session rather than putting someone in the spotlight.

Summary

Mastering code reviews is a valuable skill for developers. By following best practices, establishing a transparent process, and fostering a collaborative environment, developers can maximise the benefits of code reviews and contribute to their projects' overall code quality and success. Moreover, if you work on your code review process and develop it, you will see that the reviews will tend to go faster every day and will be less frustrating for the team.

If you come across a colleague's implementation during a code review that includes a nice feature, an out-of-the-box solution, or code that can benefit other developers – show your appreciation! Encouraging such initiatives and ideas can often have a stronger impact in terms of mentoring than solely pointing out mistakes.