I’m not entirely sure what it says about my social life, but I was recently discussing with friends the merits of GitHub pull request reviews compared to a more traditional system of code revision during software development. This blog will explain how a pull request system works and how you might use it to improve code quality.
‘Pull requests’ is a term used in Git based version control tools such as GitHub; in essence, it’s a system which allows a developer to request some code be integrated into a product. The major benefit here is that it facilitates the formal review of code changes before they are able to effect the mainline codebase of the product.
As Git becomes the primary revision control tool of choice, it’s logical that more people will start to use pull requests within the development lifecycle. We have been using these for several years at Team and find that they’re particularly useful for reviewing bug fixes and new features.
Before we continue… A Pull Request is a feature of GitHub, the online code revision control tool (as well as most Git based version controls). It makes it easier for developers to discuss code changes before integrating them in the project’s ‘production’ codebase. By ‘production’ we mean that the code will be used within the genuine product, rather than just in it’s development.
In a version control system a ‘branch’ is a safe-space to make changes away from the production code. The changes made in the branch can later be integrated through a pull-request. To put it into context: it is a request from the developer to the code owner to ‘pull’ some code changes into the ‘production’ (real) codebase for the product.
Reviews during a pull request are another tool in your code quality development kit. As with all tools, they have their purpose and things they’re not so great at. Let’s take a quick look at the pros and cons.
Advantages:
– A review during a pull request offers the opportunity to review the code before it’s integrated in the main codebase of the project. This means that you, as the code-owner, can assess the quality of the software before it’s incorporated. Did the developer update their documents? Did they follow your coding standards? If not, request changes!
– Another advantage is that you can link a fully automated test system. This can check that the code builds, that tests run without any errors and that static analysis reports no issues. This works as both a regression suite – checking that new work has not broken existing code – and to enforce the introduction of tests for new code – have tests been developed/updated? Your automated tests can be mandated as part of the review process, meaning that you have confidence the codebase remains stable as new features are added.
– As Pull Requests tend to be for features or limited fixes, the review sizes tend to be small. If you have to review just one code file using pull requests, the chances are that you will be able to hold attention throughout. You’re more likely to catch those subtle errors during the review as you’ve not been splitting attention between a large number of files! By no means is this fool proof (you will still miss things), but it’s more likely to catch issues earlier – by having smaller reviews, you spend more time on the fine details.
Downsides:
– With pull requests it can be hard to do an overall review of the codebase. Has your change subtly impacted some code elsewhere in the main codebase? The advantage of reviewing the whole codebase is that you can start to form these interactions and see the flaws which have been introduced over time. Reviews at pull request tend to focus on incremental changes, so can end up with less of an overall view (though this depends very much on the reviewer).
– Across a whole project, particularly if you have a comprehensive automation suite, the review/testing process can take longer. Each individual review is shorter than when doing a system wide review, but as the testing is done more frequently the time cost can add up. However, as the pull request system is intended to improve code quality, you may consider it to be a worthwhile cost.
Best of both worlds
It’s important to bear in mind that any review process will have both positives and negatives – there is no ‘one size fits all’ approach to reviewing code. Overall, I think that the best approach is to combine both a pull request and more traditional review system.
Reviews at pull request are ideal for looking at fine details, and for doing sanity type checking on the code. As we’ve already mentioned, integrating your automation suite here will help catch most common issues.
Then, at a reasonable frequency, take stock of the codebase. Look at doing a wider design review and make improvements to resolve any other issues. As the fine details have already been covered, you can use these to form a more holistic view of the software as a product.
By integrating reviews during pull request, the goal is to improve code quality and generally make your life easier. If you want help to improve your development processes, contact us.