When I first started working almost 3 years ago, I couldn't see the need to include anything in the description of my pull requests. I had felt that the title is enough. In some cases, this is true. But in other cases, a Fix broken ABC feature sounds vague to code reviewers. Being provided at least some context about the pull request can be helpful.
In this article, I'll be sharing 3 tips on opening effective pull requests.
1. Describe why you made the changes
Describing our changes is a great way to provide the context of the pull request (and commit). It can be helpful now and in the future. Here are reasons why. 👇
- The reviewer can view the pull request from a certain angle, providing potentially better suggestions
- Tracking down bugs in the future are easier as we would have an idea as to why certain changes were made
2. Keep the pull request small
When a pull request is big, the reviewer can feel overloaded with information. When this happens, it can affect how the reviewer views the correlation between a piece of code with another and worse, a sneaky bug can slip through. But when exactly can a pull request be considered as big?
We can use this study as a guide and follow our instincts because pull requests are unique.
A SmartBear study of a Cisco Systems programming team revealed that developers should review no more than 200 to 400 lines of code (LOC) at a time. The brain can only effectively process so much information at a time; beyond 400 LOC, the ability to find defects diminishes.
How should we decide to keep our pull requests small? Ask ourselves this question whenever we think about fixing a bug or implementing another feature altogether.
Can this be done separately? If yes, then do in a separate pull request.
3. Write a changelog
Unlike my first two tips, this is rather insignificant. Before I started describing my changes, I tend to just include a changelog to give the reviewer an idea of what to expect. Nowadays, the changelog acts as an addition to my description. A changelog could look like this.
If you find this article helpful, please spread the word!
Do follow me on Twitter to read about my findings while programming or my feelings of joy and despair while watching football. I'm also active on Instagram and Goodreads where I frequently share what I'm reading and what I've read.
Thanks for reading! ✌️
Top comments (0)