Intentional Pull Requests
The Power of asking "why" for routine practices.
In a retrospective, someone asked, “Do we know why we are doing pull request reviews before we merge code?” The reactions to the question included incredulity and pedantry. Incredulity, expressing surprise that the person asking the question didn’t know why we do Pull Requests (the person knew, they asked if there was a common understanding). Pedantry in the form of sharing the “first principles” of the “why” of Code Reviews and Pull Requests.
Something being a standard practice that our prior teams have done doesn’t mean it’s as useful as we think, or that the team is doing it effectively. Without a clear, shared understanding of why we are doing a process step, it’s hard to:
Do it the right way, and improve.
Evaluate whether the process is effective.
Work towards the common goal.
This is true of any process. In the context of Code Reviews and Pull Requests, a practice that many teams consider a process bottleneck, this is particularly important to consider as, “code review is important but can cause challenges if it interrupts workflow or if delays cause constraints in the system.”
A good review process provides feedback that is relevant, timely, and actionable, and being intentional about your process is a key part of enabling those qualities.
Why Do Pull Request Reviews?
Leaving aside the simplistic answer of “It’s part of our process and part of my job,” some of the reasons (you may think of others) people state for why they do code reviews and pull requests are to:
Find Bugs
Catch any Requirements gaps and evaluate the suitability of test cases.
Ensure that others can understand the code.
Meet a Compliance requirement.
Verify coding style.
Sharing and reviewing design.
Facilitate mentoring.
Many of these things can be better done with automated tools. And it’s not a given that review is valuable. Code Reviews aren’t the most effective way of finding bugs. As Fosgren and Humble report in Accelerate:
We found that approval only for high-risk changes was not correlated with software delivery performance. Teams that reported no approval process or used peer review achieved higher software delivery performance. Finally, teams that required approval by an external body achieved lower performance.
Style checkers or formatters can identify and correct coding style issues, ensuring compliance with the organization’s style guidelines. Since code reviews often occur when the code is ready to be integrated, that is not the right time for reviewing design decisions or providing in-depth mentoring on coding style — this can and should happen earlier in the process and in other forums.
People and Tools
It’s important to focus human review time on the things that are most effective, such as comprehensibility and whether the code does what it should. Tools to check for routine issues can help with this, but that’s not enough. A key part of focusing human review time is teams having a shared understanding of the goals and purpose of a code review, including what kind of feedback to provide, and what a reasonable amount of effort is. If you know this you can better decide:
Who is the right person to review.
What aspects of the code to focus on.
How much time to spend.
How to prioritize doing the review compared to other work.
How to measure the effectiveness of the PR process.
Whether you should do PR reviews at all, or simply allow merges after tests pass.
Identifying Your Why
Figuring out whether your team has a common understanding of why reviews are needed need not require hours of introspection. A simple survey will identify the gaps. Reconciling the gaps can be done in various ways, ranging from discussing the most valuable approach to having a manager make some assertions (though it’s better to get the team to agree). Questions like this are a good topic for the team to discuss periodically, perhaps on a quarterly basis.
Ask the people on your team why they think they are doing Pull Request Reviews and whether they feel that they are effective. You may be surprised by the answer. Then work to develop a shared statement of why. Even if the stated purpose doesn’t align with the data on what is truly effective, at least you will be working in an aligned fashion, and you can work to improve the process.
Next Steps
Create a clear statement of the purpose and goal of Pull Requests and Code Reviews, and if it’s helpful, you can supplement the statement with a brief checklist. Periodically evaluate whether they are serving the purpose. Retrospectives are an excellent opportunity for this. Also consider how review fits into the rest of your process, and what changes you can make in other areas, such as testing and planning, to make review time more valuable and less of an impediment to delivery. You may discover that what you are doing is working just fine. But the cost of checking in is small, and the value you can add to your process is larger than you might think.
Like any collaborative activity that impacts the larger team, being intentional and reflective, even in small ways, is essential to being more effective.