Going through the process of evaluating and joining a new team of professionals is always fascinating. How do we determine that we're a good match for working together? How do we establish trust and alignment in our thinking, over such a short period of a few interviews?
For the next team that I join, I want to make it easier for us to say yes to working together, by sharing as openly as possible my thoughts, values, strategies, and work style preferences. This is the first in a series of posts on these topics.
Principles
Here are the principles that I've developed over the course of my career, which I think are essential for a healthy code change process.
Every code change should be provably correct. When a colleague is reviewing a pull request, it should be straightforward for them to check that the code change functions as expected. Pull requests should always include the way in which the code was determined to be correct -- the tests that were run, the behavior that was validated.
The documentation of the pull request should explain why the code change was made, and include the key facts that led to the implementation. The diff already shows what changed. The PR description is where you capture what prompted the change, what alternatives were considered, and why this approach was chosen.
This documentation is important for several reasons: knowledge sharing among colleagues, satisfying compliance requirements that all changes are reviewed before reaching production, and encapsulating the organizational knowledge and decision-making that led to the change. When someone revisits this code in six months, they should be able to understand not just the implementation, but the context it was built in.
Where I Learned This
My first encounter with a rigorous code documentation process was at my first employer after university. I was working in the financial software industry, where there is a need for accuracy, control, knowledge sharing, and even liability connected to the software development process.
Consider that a company produces release notes describing the updates to their platform. The client's team reviews those notes to assess the risk of taking the latest release. After reviewing and accepting the release, they deploy it to production. When the release is running in production, a problem is identified.
If that problem relates to a change that was discussed in the release notes, the customer impact still negatively affects their business and the client-vendor relationship. But the principles of trust in communication can still be maintained: the client was informed, and they made a risk-aware decision.
If however, the bug was in a change to a feature that was not described in the release notes, then the software company didn't fully inform the client of the risk. That erodes the trust that the client has put in the vendor, that all changes will be accurately described and reviewed. That kind of erosion is harder to recover from than a bug.
The Documentation Workflow
The technical writing process of producing release notes, changelogs, and other project documentation is part of a workflow. The start of that workflow begins in the bug report or enhancement request, or feature definition. The developer's contribution to the process -- documenting their change, the key design decisions, the areas they tested and how they tested them -- all of that information feeds directly into the documentation that customers and colleagues rely on.
Each step in this chain depends on the one before it. Skip the PR description, and the reviewer lacks context. Skip the reviewer's understanding, and the release notes are incomplete. Skip the release notes, and the customer can't assess risk. The discipline starts with the developer, at the moment of the commit.
What Code Review Is For
The code review process is about much more than gatekeeping production. Ensuring that safe, high-quality code is shipped consistently is one of the top priorities, but it's not the only one.
The code review process, ideally, is a chance for knowledge sharing, forming team norms, building rapport between individual contributors, and an opportunity for mentorship. The review should focus on understanding why a particular implementation was chosen by the contributor, raising questions and concerns that they may not have considered, and strengthening the solution with multiple perspectives from colleagues.
The code review process is not the place for bickering over formatting or code cleanliness. Those types of checks should be automated and applied to all changes uniformly and consistently, so that the humans in the process can focus on higher-order concerns.