Code reviews can be painful. Software engineers often complain that the review process is slow, delays downstream tasks, and leads to context switching as you navigate back and forth between an open pull request (PR) and your next task. Code reviews can also be full of nitpicking and bikeshedding, making it a poor experience for everyone involved.
To remedy this problem, some engineers have even gone as far as suggesting we get rid of pull requests and code reviews altogether. While that may work for small teams at startups, I don’t think this is the right solution for everyone, especially enterprise-level companies.
Rather, there are plenty of ways we can make the code review process a better experience for both the code author and the code reviewer. Let’s consider seven of these best practices together.
#1: Keep Pull Requests Small
Every engineer dreads reviewing pull requests that have 1000+ lines of code changed. These reviews can take hours to complete, and oftentimes what ends up happening is that the reviewer begins to skim over the code rather than carefully review it.
The solution is to keep your pull requests small. Small PRs are easier and quicker to review because the reviewer doesn’t need to spend as much time building up a mental model of how all the changes work together. There is also less code changed, which hopefully equates to fewer errors, fewer comments, and fewer rounds of back and forth between the author and the reviewer.
Keeping your PRs small may seem difficult at first, but it can be done if you break down your work into small tasks and stay focused. Don’t do major refactors while also implementing new features or fixing bugs. Use feature flags in your code so you can merge small parts of new features into the master branch without it showing up in the production app.
Keep your PRs small. Your reviewers will be grateful.
#2: Use Pull Request Templates
Another annoyance is being asked to review a pull request without any context. When a PR is dropped in your lap with no explanation, you’re often left wondering, “What is this PR for? What issue is this solving? Is there a related task for this? Why was this particular approach taken?”
A pull request template is a small, configurable form you can set as the default text on every new pull request. The PR template prompts the code author to provide relevant details for their PR. Typically a PR template would ask for a brief description of what you’ve done and why, a link to the task ticket, and a test plan for validating the changes.
Good PR templates also usually include a short checklist for the code author to go through to ensure that they haven’t missed any of the basics. This checklist might include items like unit tests, docs, internationalization, cross-browser support, and accessibility.
Below is an example pull request template that I like to use for all of my repos:
#3: Implement Response Time SLAs
If you’re finding that pull requests sit unreviewed for longer than you’d like, now is a good time to set expectations as a team for how quickly a new pull request should be reviewed. In other words, what is the maximum amount of time a PR can exist before it must be picked up? One hour? Two hours? 24 hours? Your answer to that question will likely depend on the size of your team. You may also have a different answer for internal pull requests from your team versus external pull requests from other teams.
When choosing a response time SLA (service level agreement), you’ll want to find the right balance. It’s not reasonable to expect everyone to immediately drop whatever they’re doing and review your code when you post a new PR, but you also don’t want PRs to stay unreviewed for hours on end. Find the right balance that allows your teammates to get into flow state. They should be able to work on their own code and then review PRs at natural stopping points throughout the day.
Personally, I like having a two-hour response time SLA for internal team PRs and a 24-hour response time SLA for external team PRs.
Regardless of what you and your teammates decide, having a team agreement allows you to hold each other accountable. If everyone has agreed to a specific SLA and that time has elapsed for one of your PRs, you know it’s ok to start bugging people about it.
#4: Train Junior and Mid-Level Engineers
Training opportunities are everywhere. Mentoring less experienced engineers includes more than just teaching them about the technologies and languages they’re working with. It also includes teaching them soft skills like how to do an effective code review.
Teach your teammates what you look for during a code review. Help them understand what’s important and what’s not. Teach them how to communicate effectively in their code review comments, like by prefixing non-blocking suggestions with “nit.”
There are plenty of great resources on how to be a more effective code reviewer. Google’s Code Review Developer Guide is worth reading in its entirety. The guide has excellent advice for both the code author and the code reviewer. For a more cheeky resource, How to Make Your Code Reviewer Fall in Love with You is easily some of the best (and entertaining) advice for developers creating pull requests.
#5: Set Up Continuous Integration Pipelines
Code reviews become tedious when most of the comments are things like “Missing semicolon” or “Indentation seems off here.” Don’t spend time during code reviews on things that code formatters and code linters can take care of for you. Let computers automate the trivial stuff so that you can focus on the important things that require a human.
For JavaScript projects, it’s simple to configure a formatter like Prettier and a linter like ESLint for your repo. You can then set up continuous integration for your repo using something like Travis CI, CircleCI, GitHub Actions, or GitLab CI/CD.
Your CI pipeline will run these formatting and linting tasks for you along with your unit tests. If the CI pipeline fails at any step on a pull request, it will block that pull request from being merged.
Now you’ve automated several important parts of the code review, saving you hours.
#6: Use Pull Request Review Apps
Sometimes it’s necessary not just to review the code in a pull request but also to manually view the changes in the app to verify that things look good. For apps with complex setup steps, pulling down someone else’s code and running it locally on your machine may take anywhere from five minutes to an hour. What a headache!
Pull request review apps are used to automatically deploy your code to a short-lived test environment any time a new PR is created. This allows reviewers to easily inspect UI changes without having to pull down the code and run it locally on their machine. Not only does this save time, but it also nudges reviewers to be more thorough in their reviews by making it easy.
#7: Generate Diagrams to Visualize Your Code Changes
When reviewing code in GitHub or GitLab, the files are typically shown in alphabetical order. For relatively small PRs, this may not be a problem. But when there are dozens of files involved in a PR, sometimes it’s helpful to see those changes grouped together logically so you can see how they fit together in a bigger picture.
CodeSee Review Maps help you visualize what files were changed and how those changes affect their upstream and downstream dependencies. They integrate with GitHub to automatically post a comment and a diagram on your PR. You can even create interactive tours of your code to help guide your code reviewers. Best of all, CodeSee Maps are free to open-source organizations and their public repositories.
Conclusion: Best Practices for Speeding Up Code Reviews
To recap, here are seven tips for dramatically reducing your time in code review:
- Keep pull requests small.
- Use pull request templates to provide all the context a reviewer would need.
- Implement response time SLAs.
- Train junior and mid-level engineers on the key things you look for during a code review.
- Set up CI pipelines to run linters, formatters, and unit tests.
- Use pull request review apps so you can easily inspect UI changes.
- Generate diagrams to visualize your code changes using a tool like CodeSee Review Maps.
Thanks for reading, and happy coding!
Top comments (14)
Hi Tyler, I recently listened to a podcast you were in from React Roundup :D
Fully agree with your list of best practices for speeding up code reviews. I havent personally used PR review apps yet, so I will give that a try!
As a side note, I find that internal PR response time also has to depend on what kind of branching strategy a team is using. For example, with some branching strategies you get a lot of merge conflicts if a PR is open for too long. Obviously we'd want to change the branching strategy to something more sensible, but unfortunately it's not always possible to convince the team :(
Thanks Rense! That's awesome you heard the React Round Up podcast interview.
PR review apps are amazing! I'd highly recommend using them. There are plenty of good options depending on your codebase's infrastructure, but I've used review apps with Heroku, GitLab, and Render in the past, and they've all been great.
That's a great callout on the branching strategy. Long-lived feature branches are the worst, exactly for the reason you outlined: merge conflicts. I'm a big fan of using trunk-based development and merging often to reduce the amount of conflicts that build up over time. Feature flags help a bunch with that since you can merge code into the master branch even before it's ready to be enabled in production.
Thanks for reading and for your comment!
Hmm I'm still working on understanding how trunk based strategy is supposed to work, i come from gitflow myself. Any articles you could recommend?
Here is something about trunk based strategy: trunkbaseddevelopment.com/
It is quite frightened at the beginning, but it is also a great experience for the future.
This is a great resource from Atlassian as well, and they cover some of the differences between trunk-based development and Gitflow: atlassian.com/continuous-delivery/...
I hope this helps!
I agree on all the points, as experienced this myself.
Communicating in some cases is also a very important part. It could also be included in the description of a comment/ticket/whatever you use to communicate.
This is quite interesting how some see "small" like:
OK, the description is bad, but that helps a lot to speed up the process (with trusting the developer) rather than wast time checking all 400 files. In combination with #6: The pipeline will do a check if the path is fine, so no need to look into more than needed.
Great callout! I love leaving little annotations on my own PRs to help my reviewers navigate the PR. Things like an updated file path or formatting changes are great to highlight so reviewers know which pieces are important to look at and which aren't (assuming they trust the code author!).
I have also noticed that PRs created from pair programming sessions also tend to take less time, since much of the architecture discussion happened as the code was written.
You can also use a shared .editorconfig and git hooks to verify linting is done before any files show up in the PR. Verifying in the CI pipeline is also good, but a little too late in the process for my taste. I want to know right away when I've wandered from the team's style guidelines.
My advice -- review immediately, approve immediately.
Going side by side with
I recently heard about stacking pull requests. (On episode 491 of The Changelog).
I find it to be great to make small pull requests without being blocked while waiting for everyone to review everything. This way we can tell a story with pull requests that add to one another.
This is a bit harder to manage without tooling but way easier as a reviewer. And it make it possible to have feedback earlier when working on a big feature.
Nice tips, thanks!
Another simple way to speed up PR review is just to ping people: "Hey Tom can you please have a look to my PR?"
Simple but effective :)
I agree on all the points. Thank you for sharing for informative post.
Thanks for reading!
"Keep pull requests small" (I would say 'manageable') is my number one ... and, add a good and helpful description to the PR would be my number 2.