Published
Efficient, Painless Code Reviews
Code reviews are an important practice that helps promote code quality and knowledge sharing within a team. Unfortunately, many teams find code reviews to be a slow, painful process. It doesn’t have to be that way though! Every project and team is a bit different, but there are a few guiding principles I’ve found helpful for promoting efficient, painless code reviews.
1. Embrace automation.
Automate your style guide. The use of automated linters and code formatters makes it much easier to maintain consistency within a codebase and helps streamline the review process for both reviewers and authors alike. Code review should focus on bigger-picture things like functional correctness, maintainability, readability, scalability, etc. If comments are being made about basic style guide violations, that’s a sign something is probably missing in the automated toolchain.
Re-generate code as part of your CI pipeline. If you have a file that needs to be re-generated after every change to the source code, write a script for your CI tooling to verify the artifacts in version control are correct.
Invest in your test suite. Automated unit and integration tests can provide confidence that later changes to the codebase don’t break existing functionality in unexpected ways.
2. Make your code easy to review.
Keep changesets small. Nobody wants to review a 5k LOC changeset that affects many areas of the codebase and has sweeping formatting changes mingled with small, yet significant changes to the underlying logic. You may find yourself with thousands of LOC in a feature branch, but when it comes time to get it reviewed, consider breaking it up into smaller changesets that are no more than about 500 LOC each. (And if you can get it below 200 LOC, even better!)
Clean up your commit history before submitting for review. Clean up your commit history so that formatting changes aren’t mixed with logical changes and the commit messages tell a good story for your reviewer. E.g., if you refactor a file and also make logical changes, split that work into two separate commits, one for the refactor and one for the logic change. This can greatly help your reviewer know how much to focus on each change, helping them get your PR approved more quickly.
3. Be a team player.
Ask questions. When reviewing code, if you see something that doesn’t make sense or you think should be done differently, try phrasing your feedback in the form of a question. Questions promote a healthy dialog within the team rather than making an author feel they’re being “corrected”—and nobody tends to like to feel that way! It’s also very possible your teammate has already considered and ruled out your idea, so a little humility can go along way towards maintaining a healthy team dynamic.
Offer to discuss larger feedback synchronously. Comments on a PR are a great way to write notes as you go through a changeset, but if you find the conversation is spiraling or there several suggestions being made, it may be time to suggest a brief screenshare to walk through the code together.
Focus on things that are harder to fix later. While it can be tempting to nitpick (and let’s be honest, we’ve all done that at one time or another!), I’ve found it’s most helpful to focus code reviews around things that are harder to fix later. E.g., it’s fine to suggest a better variable name, but don’t get hung up on it as modern tooling makes it super easy to come back and rename things later if needed.
Additional resources
Below are a few articles I’ve found helpful in shaping my thinking around good code review practices: