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.
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!
💡 Find all these tips with and more, with more real-life examples and actionable insights in my free book Pull Requests and Code Review: Strategies, Techniques, and Best Practices for Collaboration.
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?
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!
Top comments (9)
Those are some great tips! Thanks for sharing. Specifically I'm a big fan of PR drafts: I usually make a PR draft right after I think the task is done so I can inspect all the changes I made. This gives me a chance to fix some issues I could've missed otherwise and also refreshes my memory before the actual review begins.
Yes, exactly why I think it’s important to use PR drafts and review your own PR before submitting it to the team 😊
The single tip for beginners is to not take or give code review personally. It shouldn’t be about person but about state of the code. Do not insult people even if you think the code is dumb. Just point what could be done better. And if you receive review, do not take it personally. Apply, discard or further discuss suggestions and call the day.
This is very good advice!
I would just be careful and advise to remember that there is human being at the other side of the comments. “Just point[ing] out what could be done better” might not be enough: there are different ways of pointing things out, some better than the others 😉
Nice. Not sure about the advice of creating a PR before the code is ready though - depends on the platform. Is this Github specifically, with drafts? If you create a PR and then start updating over time, doesn't hat generate a lot of notifications for maintainers?
I like the call out to being suggestive ("why not") instead of didactic ("you should") 👍
I follow a notation for my PR comments - I add a specific emoji at the start of a comment to indicate my expected severity :
ℹ️ : here's a suggestion for some better coding or wider context (informational)
⚠️ : I don't think this is great, but I won't block the PR because of it (informational)
❓ : This is not clear (I can neither approve nor reject at this stage)
🛑 : This is a bug / I don't think this does what you think / this is a practice that will cause us harm down the line , please adjust (PR rejected)
Some advice I saw in another post also recommended highlighting things you do like 💯 in a PR, as well as marking out items for improvement 😊
Thanks @taikedz for this great comment!
About creating the PR before the code is ready, yes I’m thinking about drafts on GitHub, or “WIP” merge requests on Gitlab. Usually you don’t assign people to a PR before it is ready so they shouldn’t receive notifications. But something I often do is have a look at open PRs (including drafts) to see what is happening in my team.
I love the idea of using emojis in comments to indicate the kind of comment it is, in a very visual way!
And I agree with you about adding comments to highlight positive things. Although I didn’t mention it in this post, it is one of the advice I give in the book the post is inspired by. 😉
Good post. I'll keep your tips in mind on my next PR.
Or your next code review 😉
Thank you, good thing about the draft! I guess the illustration of point 8 was meant to have a red "don't do it" icon :)
I was actually looking for some screenshots of what to press when making changes in response to a review etc. (somehow GitHub throws me on this, I am used to GitLab interface). I did not find it here but I liked the article overall, it's clear and makes good points.