How to reduce back-and-forths on a pull request ⚡️

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 😱)

gif git merge conflict

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 🙌