Practical tips for code reviews in large teams
Tags: codereview, github, pullrequest, programming
Published: 2023-10-21 19:57:23

Improving the code review process is crucial for development teams aiming to maintain and elevate their efficiency and code quality. A growing list of pending pull requests (PRs) can be overwhelming and even demoralizing. By refining the review process, teams can ensure a balanced distribution of PRs, preventing certain team members from becoming inundated while others remain idle. Striving for equality in time spent on PRs helps in fostering a cohesive and harmonious team environment. Furthermore, adhering to a standard that aims for a review time of up to just **one business day** guarantees swift feedback and fosters a dynamic, responsive development cycle. Lastly, the essence of the improvement drive is to enhance the quality of PRs, ensuring they are optimally sized, adequately prepared, and comprehensive, which in turn streamlines the entire development process.

## How to measure Code Review effectiveness
To gauge the efficacy of code review processes, it's essential to focus on team performance rather than individual contributions. Key metrics include the duration a pull request (PR) remains under review and the time a PR is in the review phase relative to its total lines of code. Monitoring the number of PRs that remain open and the volume of code within each PR can further provide insights into the efficiency of the review process.

- Measure the effectiveness of the team rather than effectiveness of certain people
- Measure time for how long PR stays in review state.
- Measure time for how long a PR stays in review state divided by lines of code.
- Number of PRs in open state.
- Lines of code in PR

This can be achieved by introducing tools for collecting information about PRs. If you use Github there is a github action [issue-metrics](https://github.com/github/issue-metrics) that can measure the average time of PRs staying in review for a certain period of time. But you can use Github API to create your own action that will collect information important for your project.


![Example of report generated by issue-metrics](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kavvtr1qq6437brkeq93.png)



## Prepare your PR
Always start by adding a **detailed description to your PR**. If a visual representation would help, consider including diagrams. Proposing a **review plan** can also be a game-changer, guiding reviewers through a logical sequence, ensuring no change gets overlooked.
Before you request others to dive into your code, look through your draft PR yourself. This self-review allows you to catch and clean up any stray comments or oversights.
Comments within your PR should clarify your coding decisions, especially if there's potential for confusion. For instance, if you addressed an unrelated bug during the current PR, mention it. This preemptive clarification can save reviewers a lot of head-scratching. Annotations act as a roadmap through your changes. By directing reviewers to specific files or explaining the rationale behind certain modifications, you make their job simpler. The added perk? You might spot errors during this annotation phase, fixing them even before the review starts.
If you've addressed multiple issues in a PR, it might be the case that you need to divide it. **PRs should be concise and focused.** A rule of thumb: if a change touches more than five files, took over a day to draft, or would require an extensive review time, split it. For example, one PR could lay out the API for a new feature, and a subsequent PR could present the implementations.

## How to review PRs of others

Treat code reviews with the same importance as any other task. Block off regular time slots in your calendar specifically for reviews. **Swift feedback is crucial – the longer a developer waits, the hazier the context becomes, making it challenging to incorporate suggestions**.
Code reviews aren't solely about catching bugs. They offer an opportunity to familiarize yourself with the team's evolving features and coding principles. Embrace this chance to learn and grow.
Your comments during a review should be lucid and constructive. Vague remarks can lead to confusion. Always aim to provide feedback that guides the developer towards the intended solution.
While platforms like GitHub are fantastic for code hosting and initial reviews, they might not be the best for extended discussions. Consider moving prolonged conversations to a platform like Slack for a more dynamic exchange.
For extensive pull requests, it can be beneficial to pull the branch into your local development environment. Tools like **IntelliJ Idea** can provide a more immersive diff view. Remember to use commands like `git merge -no-commit -no-ff` to see the changes as if you made them.

![Pull into IntelliJ](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xlxegquppgof12fv4cob.png)


If you find certain parts of the code challenging to grasp, don't hesitate to ask the author in person for clarity. It's better to pause and understand than to provide feedback based on assumptions.

## Reviewers Assignment Algorithm

There are different approaches to assigning reviewers automatically to PRs. For example randomly or using a matrix approach. GitHub provides two strategies https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team#about-auto-assignment 
An alternative approach would be to have a custom strategy where each team member has a list of reviewers from his squad, but also two temporary reviewers from other squads.
**Choose the approach which fits your team the best considering its size and feature delivering velocity.**

## The Speed of Code Reviews
While immediate reviews are ideal, they aren't always feasible. Nevertheless, a golden rule to adhere to is the **24-hour timeframe**. Aim to respond to a code review request within one business day, even if it's just an initial assessment. This ensures that the code doesn't linger in review limbo, which could delay subsequent development stages.
By adhering to this rule, it's likely that a typical Change List (CL) undergoes multiple rounds of review within a single day, if necessary. Such quick turnarounds not only streamline the development process but also facilitate dynamic discussions between the reviewer and the developer, leading to a more refined codebase.

## How to address the review comments
Instead of solely relying on Github comments, use **Slack Github connection** to facilitate communication on the PRs. It offers a dynamic platform for real-time interactions, making it easier to clarify doubts, seek explanations, and reach consensus on suggested changes.
If there's a particular comment or issue you plan to address later, leave a **TODO** tag accompanied by a task number. This ensures that you have a clear roadmap of pending actions and that these tasks aren't overlooked in future development stages.
If a particular code section sparks extended debate, it's crucial to document the decisions made. **By adding comments explaining the choices and rationale, you prevent repetitive discussions in the future.** It serves as a reference, ensuring that future developers or reviewers understand the context and reasoning behind specific code segments.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wj42qr3oq1s3iu6etfi8.png)



## Links
Google guide: [Code Review Developer Guide](https://google.github.io/eng-practices/review/)

Cisco research: https://static1.smartbear.co/support/media/resources/cc/book/code-review-cisco-case-study.pdf 

Microsoft: [30 Proven Code Review Best Practices from Microsoft - Dr. McKayla](https://www.michaelagreiler.com/code-review-best-practices/#practicereviewers)

More readings on CR: https://blog.palantir.com/code-review-best-practices-19e02780015f