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 a 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: 7 Ways to Dramatically Reduce Your Time in Code Review
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!
Also published here