In many years of writing and reviewing code, I learned a few secrets to craft better pull requests and review code more efficiently.
I poured all these secrets into my new book Pull Requests and Code Review, but you’ll find here a preview with these 13 tips, that you can already use in your developer activity.
Can you think of more tips? Share them in comments 😉
1. Create your PR before the code is ready for review
A PR draft helps you organize your ideas and document your progress, while you’re still working on your feature.
Create your PR draft as soon as possible.
2. Make people want to review your PR
The best way to get a quick and efficient review is to keep your PR small and well documented (with all the necessary context). You’ll also increase you chances for future PRs by delivering great code now!
A clear and complete PR description: the best way to get a review!
Find all these tips with and more, with more real-life examples and actionable insights in my free book Pull Requests and Code Review: Best Practices for Developers, from Junior to Team Lead.
3. Be your PR’s first reviewer
Put yourself in the shoes of your reviewer, anticipate questions and use comment your own code when you think it can help them.
Adding comments on your own PR helps your reviewers.
4. Assign the right reviewers to your PR
Don’t assign your PR to the entire world. Choose your reviewers carefully to get a relevant review, without waiting too long for approval.
Assign just the right number of reviewers, and be clear about whose review is essential.
5. Be responsive to comments
Be open to feedback, ask for clarification, say when you disagree (with respect), and always respond to comments.
Use comments to get more information when necessary.
6. If you want people to review your PRs, you have to review theirs
Everybody has many PRs to review and little free time to. If you review other PRs, you increase the chances of getting yours reviewed too.
7. You can review code even if you are a junior developer
As a junior developer, you can let others know when you don’t understand part of the code, as it should be understandable by any developer in the team.
More about it in my post How to give code review as a junior developer?.
As a junior developer, don’t hesitate to ask for clarification and share your opinion.
8. Check the right things during code review
Code review’s goal is to check for bugs and edge cases, and challenge the implementation. It should neither be used to nitpick about minor formatting or styling preferences, nor for large-scale architectural discussions.
Checking for bugs and performance issues is better than nitpicking about formatting.
9. Use the right tone in your comments
Use “why not” instead of “you should”, be open and positive and always suggest an alternative when you ask for a change.
When you think something is wrong, suggest a better alternative!
10. Be clear about whether a change is required for you to approve the PR or not
Not all comments require a change, and not all asked changes are required for the PR to be approved. Be clear in your comment if the change isn’t urgent.
Not all comments are for asking for a change.
11. Review your review before submitting it
Before making your review public, re-read each comment: check for the tone you use and ensure you provide all the context to help the PR submitter.
12. Approve the PR when the submitter made all the changes you asked
You don’t want the reviewer to wait for your approval two days after they made all the changes you asked. When you review it, assume you’ll approve it as soon as all the fixes are made.
13. Some conflicts can’t be solved in comments
When a comment thread becomes a debate in your PR, you’d better cut it off and suggest to continue the discussion elsewhere, e.g. in a Slack thread. If necessary, dedicate a meeting to it, and/or involve a third-party.
When necessary, continue the conversation somewhere else.
That’s it! What did you think of these tips? Can you think of one tip you’d like to give other developers?
Share them here in comments 👇
If you liked these tips and want to learn some more, check out my book Pull Requests and Code Review, it’s free!
Also published here.