About the author
Albert Row is a senior software engineer from the San Francisco Bay Area with over 12 years of experience as an individual contributor, technical lead, architect, open-source contributor, and manager.
Albert has been certified reviewer on PullRequest since December 2019.
Keep PRs small, limit the code to one cohesive change
Short pull requests (or PRs) are much simpler to review than long PRs. Try to break up large features or changes into multiple smaller PRs. I find that more bugs and issues slip through on longer PRs due to reviewer fatigue. I recommend keeping PRs to less than 500 lines to get the best value from your reviewers.
Follow consistent code style
If your organization has specific guidelines for coding style, follow them. This will allow your reviewers to focus on the substance of your change rather than superficial issues - haggling over whitespace is not a great use of anyone’s time. If your organization doesn’t use a linter consider bringing one into your codebase. Automating style conformance can help the whole team move faster and take personal preference out of the equation.
Make your code self-documenting
Think about your variable names and make sure they accurately describe their contents. Also, pay attention to your method names and signatures. Using good naming with short methods can make your code substantially easier for your reviewers to understand.
Try to use constructs that are idiomatic to the language you’re using. For instance, enum methods and loops can be used to achieve the same results in Ruby, but enum methods are more idiomatic and will be easier for your reviewers to follow if they’re also writing Ruby on a day-to-day basis.
Write good unit tests
Unit tests not only validate that your code is correct, they can also act as additional documentation of your code. For complex methods, as a reviewer, I will frequently read the tests first to help me understand the desired behavior of the system. After I have that firmly in mind, I’ll dive into the implementation with a better idea of what to expect. Good unit tests can help clarify and explain otherwise gnarly logic.
Document complex parts of the code with comments that show your intent as a programmer
Sometimes code does complicated things. Sometimes those things are hard to follow just by reading the code, and sometimes it’s not possible to make the code simpler. In those cases, when it’s not possible to write self-documenting code, a few short comments describing how the code works and why it is the way it is can.
Write descriptive commit messages and group meaningful chunks into each commit
It can be helpful to see the evolution of a section of code as part of the review process. When a PR gets large this can be particularly important. Use commits to create themes within larger changes. This will allow your reviewers to step through the commits on a PR to see subsets of the PR that logically go together.
Development isn’t always a linear process, but it can be worth the time to rewrite your git history before opening a PR if you have WIP commits, or explored multiple directions before settling on a solution.
Some caveats
Avoid rewriting history after you’ve pushed. This can make comments disappear, and confuse your reviewers if they’ve started a review. Not to mention, it can also break CI processes. If you want to change history, it may be good to close your existing PR and open a new one with a fresh branch. Never change history after a merge, as this can cause unpredictable behavior.
Write a good PR title and PR description
Gonzalo Bañuelos wrote an excellent article on this subject already, but the short version is this: be specific, describe both the reason for the change and the way this change achieves a goal.
Be clear, but not overly verbose. A clear description helps your reviewers gain context on what you’re looking to achieve. They can then help you make sure the change will accomplish the goal!
Provide pointers as comments for sections of the code that could use particular attention from the reviewer
There’s no rule against commenting on your own code! Dropping comments on your own PRs can allow you to provide justification for changes in-line.
This is helpful when you have thoughts that you need to share but that wouldn’t be useful as a persisting code comment. Indicating that functionality has been moved to a new location or describing the reasoning behind an approach can sometimes make more sense as a comment on a diff than as a comment in the source code.
Request reviews from the right people
Who has the context in the parts of the code you are changing? Who has sufficient time to dedicate to providing a good review? Asking for reviews from people with the right context on your change and experience with the tech stack can really make reviews go smoothly.
You might also, ahem, consider using PullRequest to augment your internal code review - we work with some of the best
software professionals in the business to provide you with high-quality feedback on every line of code you write </shameless-plug>.
Indicate when your code is ready for review
You can save your reviewers’ time and from frustration by marking your PRs as a draft while you are still working on them and only tagging people or requesting a review when your code is ready for a look.
If you’re looking for early feedback, make that clear and ask your reviewers to give you their thoughts on the general approach. This will allow them to save time and not sweat the small stuff on the initial review. Once you’re ready, you can always request the same reviewers to do another pass, this time with a fine-toothed comb.
Ask for the feedback you’re looking for
While most reviewers have items that are always on their list to check, it can be helpful to write your reviewers a little note as a comment on the PR pointing out areas of uncertainty you have, requesting specific types of suggestions, or waving them off of something if you have broken a standard pattern for a valid reason.
This can save time and give you the type of feedback you need more quickly.
Wrapping Up
Hopefully, these suggestions have given you some ideas on how to up your game and make your PRs sail through the review cycle with less stress, more clarity, and higher-quality discussion. As with everything, creating new habits take time, so I’d recommend adding one of these tools to your toolbox now, and expanding to more when you’re ready to take them on. Try to cement one practice at a time. Before you know it, you’ll see great results.
Also be sure to check out:
