What Makes a PR Easier to Review?

Code Review is a critical indicator of a team’s quality and speed. The better a team handles Code Reviews, the more efficient and valuable their output becomes. If you don’t believe this, check out the study Meta conducted with their engineering team in the comments.

Factors Affecting PR Reviewability

Recently, I explored various studies that highlight the main factors affecting how easy it is to review a Pull Request (PR). Here are the most important ones:

1. PR Size / Number of Changes

This is perhaps the most obvious factor. The more changes there are, the higher the cognitive load for the reviewer. A magic number seems to be around 50 lines of code changed per PR. Teams that adhere to this guideline report a 40% increase in production deliveries.

2. Quality of the Description

An often underestimated yet crucial aspect of a PR is its description. A well-written description that explains why the change was made, what’s being changed, and whether there are any breaking changes makes life significantly easier for reviewers and helps avoid misunderstandings.

3. Commit History

PRs with an excessive number of commits tend to get rejected more often. Clear commit messages build trust and help get your PR accepted more swiftly.

Ultimately, a good Code Review should leave everyone less frustrated and contribute to more reliable code.

If your PR is too large, it’s time to rethink your approach. If the PR description doesn’t even help you remember why you made that change, imagine what it’s like for the reviewer!

Additional Insights and Workflows

Handling Large Changes

One of the most effective strategies for managing larger features or invasive changes is the use of a “Feature Integration PR.” This involves creating a long-lived PR for major features that allows for more iterative development without destabilizing the main branch. Developers can work on smaller PRs against this feature integration branch, making reviews more manageable when it’s time to merge back to the main branch.

This approach not only facilitates easier reviews but also allows for beneficial changes that can be extracted and submitted to the main branch separately, ultimately reducing the overall changeset.

Addressing Anti-Patterns

Two common anti-patterns that lead to larger PRs include:

1. Mammoth User Stories: When user stories are overly large and detailed, developers often feel compelled to submit all changes at once. It’s essential to encourage “thin vertical slices” in user stories to promote smaller, more manageable PRs.

2. Time to Review: If the review process is slow, developers may batch several changes into one PR. Streamlining the review process can encourage more frequent, smaller submissions.

The Cognitive Load Metric

While LOC (lines of code) is a popular metric, it can be misleading. Generated code and bulk refactors can inflate this number without necessarily increasing cognitive load. It’s important to focus on the actual cognitive effort required for review rather than merely the number of lines changed.

Transitioning to Smaller PRs

Transitioning to a culture that embraces smaller PRs can be complex. If the team is used to pushing reviews ahead due to time constraints, it will take time to shift this mindset. Addressing concerns like CI/CD times and overall workflow efficiency will facilitate this transition.

Tools for PR Management

While many teams strive to adhere to these best practices, maintaining and enforcing them as a process can be challenging. This is where tools like Candid Teams come in handy. By allowing teams to configure PR goals and automatically checking and enforcing these standards, Candid Teams can greatly improve the PR review process.

Conclusion

In conclusion, while small PRs yield faster reviews and are generally a best practice, transitioning to this workflow requires thoughtful consideration of team culture, user story management, and process efficiency. Fostering an environment that encourages smaller, well-documented PRs will undoubtedly lead to a more efficient and effective engineering team.

Do you have any tips that make a difference in your team? Or are you struggling with giant PRs? Let’s discuss!