How to create the perfect Pull Request?

Writing excellent code is as important as helping other people to review it

In software development, the output of a development team, i.e. the rate at which the team is pushing out features, depends on mainly 2 factors - the programming speed of the developers, and the speed at which code reviews happen.

Even if your team comprises of excellent developers, it does not guarantee that the output will be fast-paced. The bottleneck is usually the code review process on the Pull Requests.

Isn't your Pull Request backlogs piling up with so many iterations of comments and rectifications? What is the oldest Pull Request opened in your team's backlog?

I have observed, there are 3 types of Pull Requests -

1. Minor Bug fixes, which don't receive comments and get merged very quickly.

2. Modifications to an existing feature that receive 1 or 2 comments and also get merged quickly

3. A big pull request which receives many comments and has many iterations of review changes and comments. - This is the culprit for slowing down your team's pace.

In this blog, I have mentioned 8 ways in which you can make your pull requests easier to be reviewed.

1. Make small Pull Requests (PR)

Creating small Pull Requests come with a lot of benefits - they are easier to review, code review is thorough and they will get merged quickly. Bug fixes and debugging are also easier if the PRs are small (as you would know which PR caused which bug ).

How important this point is can be understood from the fact that Google's development team has created a separate document on Small PRs.

So how do I create small Pull Requests for big changes?

It's simple actually.

- Split big changes into small parts and incrementally create PRs.

- When creating changes for a big feature, you can create small PRs and set the target to another base branch and not to `develop` or `master`.

2. Naming the branch and the Pull Request (PR)

I generally name the branch on "what the code is doing" and I name the PR on "what problem the change is solving". You should follow the naming convention your organization uses. Make sure that the title of your PR conveys the context of what to expect in the changes.

For example, if the feature requirement is to add demographics to the profile information,

I would name my branch as "adding-age-education-location-information-in-users-table"

My Pull Request title would be - "Added Demographics Information mentioned in [PL-1001]"

3. Write a good description for your Pull Request (PR)

The description of your PR should contain the following things:

• Contain additional information which could not be expressed by the PR title.

• A link to the ticket or the ticket reference id to give more context to the reviewer as to why the Pull Request was needed in the first place.

• A bullet point list of the actual things done in the Pull Request

(Don't put information required to understand the code in the description. The purpose of the description is to provide the reviewer with a bigger picture of what to expect in the Pull Request, hence it should be brief)

Here's a snapshot of what my Pull Request description looks like.

4. Comment on your own PR

Yes, you read that right! The idea here is to anticipate certain questions the reviewer might ask and put comments at relevant places on the Pull Request. The comments can also have things on which you want input from the reviewers.

For example, questions like - "Why did you go for this approach? Why a certain thing was required? Why did you create a new API and not modify the previous ones" etc. can be answered in advance so that an extra review iteration can be skipped.

Also, explain why the code exists. ("It's like that because of these reasons. Would it be more clear if I rename this class/file/method/variable?")

If you feel that answer to these questions may be useful for future developers as well, put it in the code comments itself (good coding practices xD) instead of commenting on the PR.

5. Be prompt in responding to code reviews

This method may be time-consuming and involves lots of context switches, but it will improve the overall team efficiency. The Code reviewer will remember the code if you reply faster, and hence it will save their time and you will be able to deliver faster.

Pro Tip: You can use the Pomodro Technique for managing tasks. It's a time management technique to help you focus better in your work.

6. @mention individuals that you specifically want to involve in the discussion

This is to ensure that there is no communication gap among the team. Comments like - "@rohit any concerns with this approach" or "@manager I am allowing this API for public access. Any concerns ?" or "@alex would you like to add comments" are a must. The idea here is don't assume things, get them clarified.

7. Approach for verbal discussions if required

Ask for clarifications if you don't understand any feedback, if communication isn't properly happening via comments, approach the reviewer for a quick discussion - virtual discussion over video call or face-to-face meetup. This will clarify a lot of things quickly and save both of your time.

8. Be grateful for the reviewer's suggestions

Reading someone else's code and suggesting changes requires lots of effort. Lead with an expression of appreciation. After all, they are your teammates.

And that's a wrap!

Follow the above steps to improve the efficiency of your team's code review process. While it is a good practice to follow the above-mentioned points, there is no hard and strict rule for writing Pull Requests. Explore and experiment what works out for you. Let me know in the comments if there is something else that worked for your team.

Hi, I am Gourav Dhar, a software developer and I write blogs on Backend Development and System Design. Subscribe to my Newsletter and learn something new every week - https://thegeekyminds.com/subscribe