There are some pull requests that are more daunting to review than others. Some struggle to find reviewers and to be merged while others don’t. How to tell them apart? And, more importantly, how do you make sure yours land faster and with fewer bugs?
One aspect you could look at is size. In many cases, the number of lines touched can act as a proxy to how difficult it’d be for others to review. While useful, it is a weaker predictor than others we have available.
As an example of how this heuristic breaks, imagine you’ve got two pull requests. The first one adds 1_000 lines of code in a single file (JSON) that already exists, and it doesn’t touch any logic. The second pull request touches 100 lines of code across four different subsystems. Without knowing anything else about what any of them do, which one would you deem as of having a bigger risk? The size heuristic predicts the first one would be 10x riskier, because it’s 10x bigger in size than the second. However, the second interacts with many subsystems, while the first only with one and it looks like new configuration for something that may be well accounted for. The number of subsystems involved increases the surface to account for: any one of the changes to the subsystems needs to be understood, as well as the interaction of them all together.
This predictor can be formulated as follows: how many questions does the pull request answer?1
The fewer questions any change addresses, the easier it is for reviewers and the author to understand the edge cases and come up with better solutions. It’s also easier to agree about direction, which is an important aspect of pull requests. In the limit, pull requests that answer a single question provide less surface to explore, and so they land faster and come with fewer bugs.
- I consider this heuristic a derivative of Claude Shanon’s it’s easier to make two small jumps than one big jump in any kind of mental thinking. Code is just another expression of thought. ↩︎
Leave a Reply