Having your code reviewed is a great opportunity to improve but it can also be very time-consuming at the beginning.
The more comments or requested changes you get, the more time your pull request waits before being merged.
If you work on a big codebase, this means... more possible merge conflicts!! (Noooooooo 😱)
If your team is struggling with pull requests taking too long to merge because pull requests bounce back and forth a lot, here's 6 tricks you can apply to shorten the code review process:
1. ✂️ Don't hesitate to split user stories
A user story is a description of a unit of work that needs to be done. It is usually written from the perspective of the user.
A user story (or ticket) should be scoped to a single feature that a user can do in the system being built.
Scoping a project in small tickets has the following benefits:
- allows to ship features faster
- keeps the team motivated
- makes code reviews easier (less changes on a pull request)
At Doctolib, all tickets are expected to take between 1 to 3 days of development. If a ticket is supposed to last longer, we have to split it
2. 💡 Clarify what needs to be done before development starts
If there are still uncertainties regarding the feature, don't hesitate to discuss with the relevant people to find answers before you start coding.
It's harder to keep an eye on the big picture when you start coding (because there will be other issues to fix!), so you better start with a clear idea of what's expected.
From a functional point of view
- Discuss the output, edge cases, final design e.t.c. with the Product Manager
- Don't hesitate to challenge their vision if you think of another technical solution
From a technical point of view
- If you're not sure how to implement the feature, discuss the possible solutions with the other developers or your manager
3. 📝 Add context to your pull request
- Add the ticket link if there is one
- Add a short description of the pull request if there is no ticket
- Explain why you chose this specific solution if you hesitated with another approach
- Add comments if you feel it's necessary
4. 📍 Tag reviewers when the pull request is 100% ready
- Wait for all tests to pass
- As the author of the PR, add the relevant comments and PR description beforehand
5. 🧐 Contact the author of a comment you don't understand
- If a comment is not clear enough, reach out to the person and make sure you understand what they meant. This will reduce the noise of back-and-forth clarifications in the PR and will allow you to get your answer quicker!
- Then document the answer in the conversation in the pull request, to make sure everyone has access to the answer
6. 🙅 Don’t hesitate to challenge some comments
- I know it can be hard to challenge or refuse a comment (especially as a junior or as a new joiner) BUT you can!
- Problem is: when applying all comments immediately, you can get the opposite feedback by the next reviewer… which can lead to a lot of back-and-forths.
- When not sure, you can check with a third person if a comment is relevant or not.
I hope you enjoyed this article!
I am particularly interested in the topic of Code Reviews and reducing the back and forth on a pull request can definitely lighten the process!
If you're interested in how to be a great reviewer too, I have written an article about it:
Also, feel free to reach out to me if you want to add anything on this topic or have some tips you’d like to share! I'd love to hear about them 🙌
Oldest comments (5)
Spoiler alert: just don't open one and force push master (or main). Life is too short for anything else.
The only way that I know to completely reduce back-and-forths on a pull request is to not use them.
Instead, embracing practices as Continuous Delivery/Deployment in main branch + Feature Toggles + Pair Programming.
Even though it might seem cool, it comes with a lot of different challenges and assumptions, and done wrong can cause disasters.
Being honest, after I have been involved in three teams doing it, I won't come back to PR. I prefer the benefits and pains that CD brings over the pains and benefits of Pull-Requests.
But meanwhile you still need to use PR, this reference is a good starting point to get the process more smooth and less frustrating 😁
Very good advices ! Thanks.
I would add one of mine : choose with high acuracy notifications settings from Github, to drastically reduce the time on iteration loops on comments.
Some integrations really useful for that (Slack reminders for exemple)
This is great advice, especially point 3.
I also like to raise pull requests really early as drafts, with anything I think that might be controversial. This way I can get feedback really early in the process before I've committed to the implementation and written all my tests etc. I've found this leads to much quicker final reviews as everyone is aligned on implementation details already.
One piece of advice here that is missing I feel is don't underestimate a simple phone call. Often that can cut down on back and forths.