The Art of Creating Efficient Pull Requests
Pull Requests (PR) are crucial to almost all software development these days. They have became a lot more accessible and easier to perform thanks to all the various features from different source control platforms such as GitHub and Bitbucket.
However, PRs are still considered by a lot of the developers mostly as something that need to get approved in order to get their code merged. They often treat it as a hide and seek game and try to hide things from reviewers.
Why do we send Pull Requests? Let’s take a step back and reconsider the main purpose of sending a Pull Request.
Pull Request is to ask others to help you have a look at your codes and give you feedback. It is a mechanism to learn from others.
Helping you have a look at your codes is the key takeaway here.
Whoever reviewing your PR is doing you a favor. They are spending a lot of their time trying to help you catch potential issues before they show up as bugs in production. In order to do so, they have to spend a significant amount of their time to try and understand what you are trying to achieve on top of their busy schedule and workload.
What Does a Bad PR Looks Like
This is a very good example of what not to do when sending a PR.
How many bad things did you notice from the above PR? Imagine someone from your team send it to you and ask you to review the PR.
An abstract title, only the auto generated list of commits messages in the description section, 100+ files being updated with just 6 commits.
How long will it take for you to properly review this PR assuming you are not familiar with what they are trying to achieve or the details of the task they are working on? Will you still try to give a good code review or like most of us, will you simply click “approve” after a brief scroll through the code?
Remember, why should the code reviewers care if the one requesting code review doesn’t?
3 Ways To Improve Your Pull Requests
Now that we know what we shouldn’t do, let’s have a look at what we should be doing.
Here are 3 simple points to make it easier for your code reviewers to review your code quickly and efficiently. Not only your codes will get reviewed faster, it will get reviewed more thoroughly.
1. Keep It Small & Keep It Clean
Don’t do one big commit with all of the different changes— indentation fixes, refactoring, and then the actual important changes.
Organize your individual commits and keep them clean. Put all the code clean up — indentation fixes, simple refactoring — in a separate commit and mention it in the code review description. That will allow your code reviewer to be able to review the PR commit by commit. They can go quickly over the cleanup commit and spend more time on commits which include the actual important changes.
In order for this to work, the commit message should be descriptive enough so that the reviewers will know which one they can skim through and which one they should pay attention to. And make sure each commit is grouped by feature or function. If not, the code would not make sense to the reviewers when they review commit by commit.
Using git rebase and selective commit make it easier to keep your commits small and clean.
2. Provide Overview & Background Of What You Are Trying To Do
Description should contain the overview of the feature or the background about the changes. Your reviewers are busy and occupied with their own tasks. Don’t expect them to know what you are working on. Provide screenshot if it helps make it easier for the reviewers — especially for UI changes.
- It should not be just repeating the relevant comments that have already been put in the code or the commit messages. Instead, cover why the changes are made or the overall feature that is implemented by the PR.
- If the PR is for a new feature, then indicate the unusual cases which have been considered in the description — if nothing is specified, then it will be assumed that corner cases are not yet considered and the reviewer can put some focus on those cases while doing the review. This will help reduce the number of bugs found by QA or worse, bugs in production.
3. Mention Areas of Concern Or Area You Want To Get Reviewed
If there is any particular area you would like to get reviewed, then mention them in the PR. It allows the reviewer to pay more attention to those areas - things concerning performance, use cases, architecture, design etc.
For PR with complex changes, try to annotate code before the code reviewer starts reviewing. Annotations will help guide the reviewer through the changes, showing which files to look at first and you can also explain the the reason behind each code modification. It helps ease the reviewing and also provides more context to the reviewers.
Wrapping Up
There is no definitive right or wrong way when it comes to pull requests. Each teams has their respective definitions of optimal pull request size and format. And there will always be situations where a small PR might not be possible.
Communicate with your reviewers and try out different ways to improve the code review process of the team. The small time that was spent on improving the code review process will save the team hours of debugging and releasing patches later down the line.
