The One Thing You Should Do to Make Your Code Reviewers Happy

Practical Guide to Managing Branches and Creating Smaller Diffs for Better Code Reviews

Aug 20, 2024

While working for a globally distributed team at a $1.7B GenAI startup, I’ve realized the importance of keeping diffs small in pull requests (PRs).

I’ve noticed that both my coworkers and I are less likely to review a PR if the diff is too large compared to smaller ones. Additionally, when a PR is big, we’re less likely to review it thoroughly.

In this article, we’ll explore the benefits of having smaller diffs and how effective git branch management is necessary for success.

✅ Why We Should Have PRs with Small Diffs

Focus: Small diffs allow reviewers to focus on specific changes, making it easier to understand the logic and intent behind the code.
Thoroughly reviewed: Reviewers are less likely to miss bugs when the changes are small and manageable.
Quick Reviews: Smaller diffs can be reviewed and approved more quickly. Your coworkers are more willing to review a 150-line PR than a 600-line PR.
Fewer Conflicts: Smaller diffs reduce the likelihood of merge conflicts, as they touch fewer lines of code and interact with fewer parts of the codebase. Additionally, any merge conflicts that do arise are easier to resolve.

How to Handle Your Branches

One downside of small diffs is the need to manage multiple branches efficiently.

Let’s walk through a practical example of how to manage your branches.

Imagine you’re starting work on a new feature called feature-1. You begin by implementing it on a branch called feature-1-diff-1, and after two commits, you're ready to create a PR. At this point, your Git history looks like this:

While the first PR is under review, you continue working on the feature on a new branch: feature-1-diff-2.

You make three more commits, and now you’re ready to create your second PR.

When you open the second PR, make sure not to select main as the base branch for the merge. Instead, choose feature-1-diff-1 as the base. This way, the reviewer will only see the new changes you made in your second PR, not the changes already included in the first PR.

Now that your first PR has been reviewed, you add an additional commit to address the comments:

Git history after resolving comments in your first PR

You squash-merge your first PR into main:

If you check the state of your second PR, you’ll notice that the base branch has automatically changed to main because you merged your first PR. As a result, your PR will now show several merge conflicts since the commits 9f8e7 and earlier are already in main.

To avoid resolving these merge conflicts manually, go back to your branch feature-1-diff-2 and rebase it onto main:

Ensure your local main branch is up to date with the latest commit.
Rebase onto main with the following command: git rebase -onto main 9f8e7.
Finally, force-push the changes to your remote branch.

When you check your second PR, there won’t be any merge conflicts from the 9f8e7 commit and earlier (though keep in mind that a merge conflict could still occur due to the c3d4e commit).

Your Git history looks like this:

I’ve been applying this technique for the past few months, sometimes managing up to three or four branches simultaneously. My goal is to keep PRs within the range of 100–400 lines changed.

I’ve noticed all the positive effects I outlined earlier. It’s easier for my colleagues to review the PRs, and they’re more likely to review them thoroughly.

❌ What Are the Downsides of Smaller Diffs?

Some downsides to consider are:

Managing Multiple Branches: You need to manage several branches to avoid unnecessary merge conflicts. However, once you get the hang of it, the process becomes straightforward.
Lack of Context: In your PRs, you’re only showing parts of the final result. This can make it difficult for the reviewer to understand the bigger picture of what you’re trying to achieve. Make sure to link relevant design docs, PRDs, or Figmas.