6 Ways to Make Pull Requests More Reviewable

What is a pull request? 🤔

A pull request allows developers to add new features or fix bugs without affecting the main project code or the experience of the users. They can write and test code updates locally without worrying about disrupting the overall product this way.

But if you’re a developer yourself, you must already know that. 😎

I have been working on helping engineers review code through Axolo for more than a year now. And before that, I already had reviewed hundreds of pull requests so I'll try to share what I've learned so far. I’m writing this article today to help engineers design their pull requests so that it will be easier for their teammates to review them. And an easy review usually means a faster one!

How to open better pull requests  🤙

I tried to summarize easy and quick takeaways for a better pull request design.

Let the computer do the boring part 🤖

Your time and mental stamina are scarce, do not waste them. Code review should not be about checking styling, tests, builds, or unused variables (this might sound obvious to some but you should know that it isn’t for everyone). 

There are four actions that you should automate, such as verifying:

1. code builds (with Continuous Integration tools),
2. that tests pass (with Continuous Integrations tools),
3. code styling or whitespaces (with code formatting tools),
4. unused variables or imports (with code linters).

If you need to check one of them, find a way to automate this task for next time. 

Show your intentions 🤝

Acknowledge that anyone in your team could be reading this pull request, even if you specifically choose your reviewer(s). The content and tone of your initial comments should objectively inform them of the reasons why you opened this pull request, and what is your solution.

Help your reviewers start their review by giving a lot of context in initial issue or code comments. 

Limit the impact of each pull request on the codebase 🙏

In our team, we’re big advocates of the single-responsibility principle. According to Wikipedia

“The single-responsibility principle (SRP) is a computer-programming principle that states that every module, class or function in a computer program should have responsibility over a single part of that program's functionality, and it should encapsulate that part.”.

Applying the SRP to pull request means that if during the development of your pull request, you notice that you’re creating two separate services (even if one depends on the other one), you should open a second staked pull request on top of the first one. That way, you will reduce a big chunk of changes into two separate tasks, and help your reviewers a lot. 

Your pull request should speak for itself 💭

If you are changing the front of any application, there are chances that you’re affecting something visually. So please, copy screenshots in the pull request to help your reviewers. 

Is a part of your code a bit painful to understand? So you should have written dedicated comments within the code, but you can also write some code review comments before your reviewers arrived. You will pave the way for their understanding!

Use a pull request template 🖌

When you open a pull request on GitHub, you can use a pull request template to have a preset text for your organization. It is very useful to ensure that every pull request follows a uniform process and to have a to-do list for the author to check before seeking a review.

We wrote a dedicated article where you will find a thorough explanation about them and 6 different pull requests templates for you to copy/paste. 

Provide all the necessary information to test your code 😇

Testing isn’t fun, and what’s more frustrating than not knowing how to test someone else’s code? You should provide all the necessary steps to reproduce and test your pull request for the reviewers. Are there some new packages to install? Or a specific command to start? Details all the way to operate your code so your reviewer doesn’t waste time trying to find out.

I hope these 6 quick tips to improve your pull requests might help your team! The last tip would be to detail a clear review process with your colleagues. We started Axolo as an internal project out of PR frustration (inactive pull requests are badly affecting engineering workflows) and decided to launch it last year. If you like communicating within Slack, you should try it out, if not, you should find your own tooling to detail your review flow.