13 tips for better Pull Requests and Code Review
Posted on October 17, 2023·
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.
Tell me if you find them helpful, or if you can think of some more 😉.
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.
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!
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.
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.
5. Be responsive to comments
Be open to feedback, ask for clarification, say when you disagree (with respect), and always respond to comments.
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?.
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.
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.
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.
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.
That’s it! What did you think of these tips? Can you think of one tip you’d like to give other developers? Let me know and I may add it to the list 😉.
If you liked these tips and want to learn some more, check out my book Pull Requests and Code Review, it’s free!
Check my latest articles
- 📄 The simplest example to understand Server Actions in Next.js (August 3, 2023)Server Actions are a new feature in Next.js. The first time I heard about them, they didn’t seem very intuitive to me. Now that I’m a bit more used to them, let me contribute to making them easier to understand.
- 📄 Intro to React Server Components and Actions with Next.js (July 3, 2023)React is living something these days. Although it was created as a client UI library, it can now be used to generate almost everything from the server. And we get a lot from this change, especially when coupled with Next.js. Let’s use Server Components and Actions to build something fun: a guestbook.
- 📄 How to give code review as a junior developer? (June 24, 2023)By focusing on learning, providing constructive feedback with a positive tone, and embracing the opportunity to contribute, junior developers can make valuable contributions to code quality and their own growth. Code reviews are essential for skill development and fostering collaboration within development teams.