Reviewing someone else's work is often challenging and time-consuming. It can easily lead to procrastination, frustration, or even tension between developers. Yet, it's an essential part of our daily workflow and deserves careful attention.
Below are a few unordered tips we've gathered over time to make reviewing pull requests easier (from the author's perspective) to help prevent issues before they arise.
We use GitHub, so some examples are specific to it, but the same ideas apply to most alternatives.
1. Write small pull requests
This is the most common (and probably the most important) advice. To reinforce it, we automatically add t-shirt-sized labels to our pull requests. This encourages authors to keep them short and reassures reviewers that the review won't take too long.
2. Always prioritize readability
This applies not only to the codebase itself but also to the files diff. Don't hesitate to add code comments that provide context (eg. data format examples) even if they seem redundant with TypeScript types or equivalents. Anything that helps someone understand the code outside of an IDE is worth including.
3. Create a simple template
Use GitHub pull request templates to make authors' work easier and ensure consistency across pull requests. A short template with three or four sections (and maybe a few checkboxes) is often enough to remind authors of key steps in the process.
4. Explain why it's done in the description
Include any relevant specifications, documentation, or conversations related to the pull request. This not only helps the reviewer but can also help yourself realize if something has been overlooked (which happens more often than we'd like to admit). Plus, even if the reasoning seems obvious now, it will help future developers understand the decision (especially years down the line). Obviously, make sure to explain how the feature is supposed to work.
5. Explain how it's done in the files diff
Before requesting a review, review your own diff. You might catch accidental commits, hard-to-read code, or even mistakes. It's frustrating for reviewers to find easily avoidable errors. Also, force yourself to add helpful comments in the diff: I personally often find that they actually belong to the code itself and add a commit for them.
6. Help the reviewer with tips
I often add "guided tour" comments in the diff, like suggesting to "review with whitespaces ignored" or to "review commit by commit". These small hints can make the process much easier. You can also mark some code lines that are open to discussion or feedback. Encourage the reviewer to be part of the collaboration, not just a gatekeeper.
7. Make a unique commit for renaming or moving files
Whenever you rename or move files, make it a separate commit from content edits. (Git and GitHub sometimes detect this automatically, but not always.) This allows reviewers to skip the rename commit and focus on the real changes, instead of a massive "deleted and added" diff. This practice made our TypeScript migration much smoother for instance.
8. Rebase commits
Coding is rarely linear, mistakes are made, sometimes fixed a few days afterwards. Before opening a pull request, consider taking some time to rebase commits to make the history more readable. Don't try to make it perfect, but at least regroup commits that belongs together so it makes more sense when reviewed.
9. Suggest a pair review if necessary
For complex pull requests or ones that require intricate setup, a pair review might be faster and more productive. It's also a great opportunity to explain your code out loud: often, you'll discover parts that are hard to justify or could be simplified.
10. Kill your ego
Take feedback with an open mind. Make reviewers feel appreciated for the time they spend on your work. This way, they'll be more eager to review for you again. Remember that it's usually more valuable to make the reviewing process smooth and collaborative than to be "right" at all costs. That's easy to forget when we're deep in the work.
I hope those tips can help making this complex task smoother in your daily workflow!
Top comments (0)