Do you subscribe to the philosophy that pull requests should be a pleasure to review? This blog explores several ways in which this can be achieved.
If you're reading this blog post, you have probably felt the pain of a 4,000 line pull request with no description or context. No one should roll their eyes and groan upon opening a pull request. If you share the belief that the onus of making them a pleasure to review is on the engineer putting up the pull request, read on.
There are several code pull request tools that make reviewing code that much easier. Here are a few of my favourite GitHub pull requests:
Reviewable organises the review in a nicer UI than Github’s native view, it has plenty of keyboard shortcuts to aid when reviewing. You can also review by commit if you want using Reviewable.
Did you know that if you press the full stop key whilst on a Github repo you’ll be taken to a web version VSCode? This works for pull requests as well. You can clearly see all the files changed and make comments in IDE as you please.
Similar to above, Better Pull Request for GitHub is a chrome extension that lets you browse the files changed in an IDE like tree structure.
Codacy automates some aspects of code review which can be extremely helpful. With Codacy, you’ll be able to remove mundane code review activities (such as code style) and streamline the often time-consuming task of coding new applications.
Pre-commit/pre-push hooks using Husky. These tasks are run locally before you commit or push code; they can do things such as run tests, run lint checkers and check commit messages and they’ll catch things that could have otherwise slipped through. Husky should help to simplify the code review for the reviewer.
We’ve recently started using pull request templates at Brightec. Pull request templates provide a template for the engineer to fill in when writing a pull request.
We don’t enforce descriptions in pull requests, however I have found that if you include a template the engineer will likely fill the fields out and provide the reviewer with some context. This is especially useful when you are reviewing a feature/project you’re not currently working on.
To add a template to your project you’ll have to create a pull_request_template.md file, this can be visible at the root of your project or hidden inside a .github/ directory. Here’s the pull request template we’ve adopted (click raw to see the raw markdown file):
This pull request template is useful as the engineer thinks about the change they’ve made in plain English, thus making the pull request clearer for the reviewer. Learn more about pull requests templates here.
Imposing a size limit makes pull requests more concise and easier for the reviewer to digest, meaning they may be able to catch any potential mistakes using less effort.
The relationship between cognitive load and the size of the pull request is exponential; at a certain size the reviewer won’t even read the code and bugs will slip through.
To combat this we’ve imposed a size limit of 400 lines of code on pull requests. Under this limit we sometimes need to break down features into multiple pull requests (i.e SQ4-123-a, SQ4-123-b, SQ4-123-c, etc.) and have found code review more effective in doing so. The commit history does become slightly messier, however we feel it’s a worthy tradeoff. Afterall, the less the reviewer has to think about, the more they’ll catch in the review.
A 400 line limit might not be right for your project. There’s an interesting tool which benchmarks your organisation against others in the industry.
It’s always worth considering; would you enjoy reviewing your own pull request?
This is a technique that I use personally. As silly as it seems, I pretend that I’m the reviewer and review the code I’ve pushed myself first before asking anyone else to do so. I leave comments for myself and resolve them once I’ve fixed them.
Even with all the pull request tools I’ve written about above I still catch things in reviewing my own code. I’ll then request a review from somebody else and hopefully I’ve made the reviewing process more pleasant for them, while reducing what could have been missed before it is merged in. It’s one of the ways I get the best out of code reviews.
With these Pull Request tools in your arsenal, you can make pull requests less painstaking, maybe even enjoyable, for the reviewer. If you have any more suggestions, please let us know. We love to hear and explore new ways to improve our process.
Search over 400 blog posts from our team
Subscribe to our monthly digest of blogs to stay in the loop and come with us on our journey to make things better!
We develop intelligent mobile apps for iPhone & Android that deliver for you.
Want to connect? You can find us on Instagram, Facebook, X (formerly Twitter) and LinkedIn.
Here’s our privacy policy.
Here’s our Accessibility statement.
Copyright © 2024 Brightec Limited. All rights reserved.
