As a developer, one of the key skills to build and develop early is to have an efficient development process. One of the simplest things to incorporate in this process is to strive for small pull request / changelists / code reviews. Some big tech companies have built into their culture to help new developers build this habit right from the start. They might even go as far as have defined policies such that your change will get rejected from reviewers for the sole reason for being too big. Irrespective of the current team culture, it is imperative to think about optimising your process to ensure the quickest turnaround time to get your code changes to production.
How do you define “small” ?
As a general guideline, a pull request should be self contained and address just one thing in a specific context. i.e. the smallest functional piece that adds value (not a partial change that breaks the build :P). By way of an example, let’s consider that you’re implementing a new API. One way you could split this up is:
A pull request for the API contract. This will be a great way to get feedback on the API design, its interaction with the customers and how will it handle possible future usages.
Once that’s approved and merged, move on to the implementation and tests. This is a way to get feedback on code quality and testing correctness.
Once the implementation is pushed the next possible change could be the use of the API; e.g.: on the front end with the required change to the UX.
Amazon’s guideline is to think of the scale as a 150-150 line change (150 lines of code and 150 lines of tests), and Google guidelines are approximately between a 100-200 line change.
So, why small pull requests?
Effective and productive review:
Smaller changes are easy to get reviewed from your team. For example, reviewers will not have to block out 30min/1hr sessions for reviews.
The change can be reviewed thoroughly and you can get pertinent feedback from reviewers rather than just a “LGTM” at the end of a 4 page change with just some method name change suggestions.
Quicker turnaround time for features:
As each change is small, the amount of back and forth for incorporating the requested edits will decrease.
Working on bigger changes mean, longer review time which in turn results in more conflicts to manage during merge. Smaller changes mean, easier and more frequent merges.
If the reviewers deem that there is an issue with the approach/design of the change, a small change means lesser wasted time and effort to re-implement.
Splitting features into smaller reviewable changes also means less time being blocked on reviews while working on the subsequent change.
Better maintainability for the system:
Smaller changes are easier to design and align on. Within the context of the feature, it will also provide a way to continuously make the code better with relevant refactors that sometimes get missed due to the scale in larger pull requests.
It is less likely to introduce bugs as each merge has fewer changes and the impact of the change can easily be assessed. As a result, testing will be more directed making bugs easy to identify.
Smaller changes also mean easier rollbacks. When using larger PRs it is very likely that there are changes across multiple files spanning multiple functionalities. Additionally, the longer review time means there would be other intermediate changes that get pulled in as part of the merge making rollbacks unnecessarily complicated.
Note: There maybe cases where the change has to be bigger, e.g.: refactors where multiple files are deleted, refactor from an automated tool, incorporating a new code formatter, upgrading a dependency version that changes the imports across multiple files etc. These need to be evaluated on a case by case basis but you should think of these as the exception and not the rule.
In conclusion, incorporating small pull requests and code reviews into the development process can greatly enhance efficiency and productivity. By breaking down changes into smaller, self-contained pieces, developers can benefit from more effective reviews, quicker turnaround times for features, and better maintainability for the system. While there may be exceptions for larger changes, the general guideline of focusing on smaller pull requests can lead to a more streamlined and successful development process.