Pull Requests Best Practices
How does a good pull request look like
As a leader, you must be able to define and help your team to maintain standards.
Standards are good. They ensure security regarding changes on the codebase and help your team to move fast.
One of the first things I walk through with new engineers on the team is to show how we do pull requests and why we do this way.
Here are 3 rules we try to follow when creating pull requests:
—
1. Title and Description
When creating the PR you should care about the title and the description.
Imagine that the code reviewer is arriving in your team today without knowing what is going on, and even so, they should be able to understand the changes.
The title should be sufficient to understand what is being changed.
Some examples:
Make a useful description
Describe what was changed in the pull request.
Explain why this PR exists.
Make it clear how it does what it sets out to do. E.g: Does it change a column in the database? How is this being done? What happens to the old data?
Use screenshots to demonstrate what has changed.
2. The size of the pull request (LOC)
The first step to identify problematic pull requests is to look out for big diffs.
There are several studies showing that its harder to find bugs when reviewing a lot of code.
In addition, large pull requests will block other developers who may be depending on the code.
But how can we determine the perfect pull request size?
A study of a Cisco Systems programming team revealed that a review of 200–400 LOC over 60 to 90 minutes should yield a 70–90% defect discovery. Source
With this number in mind, a good pull request should have between 200-400 lines of code changed.
Note that this won't be easy to follow depending on the programming language/framework.
Don't get trapped to that value, but make sure you established a LOC limit so your team can produce smaller pull requests.
3. Single responsibility principle
The single responsibility principle is a computer programming principle that states that every module or class should have responsibility over a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class.
Just like classes and modules, pull requests should do only one thing.
Pull requests that follow the SRP reduces the overhead caused by revising a code that attempts to solve several problems.
Before submitting a PR for review, try applying the principle of single responsibility.
If this code is doing more than one thing, break it into other Pull Requests.
—
Recap
Pull request size
It should be small. Try to create pull requests with a maximum of 250 lines of change.
Single Responsibility Principle
The pull request should do only 1 thing.
Title
Make a self-explanatory title describing what the pull request does.
Description
Detail with what was changed, why it was changed, and how it was changed.