The Rule of Two
At what point in a software project’s lifecycle should I start caring about typical engineering quality concerns such as tests, documentation, code review, decomposition? Here’s my Rule of Two: Code quality matters whenever two or more software engineers touch the code base.
For example, in a team of three working on a shared code base, the benefits of cementing behaviours as tests, of improving the code base and sharing knowledge via code reviews, or of communicating mental models and design choices through inline code comments or RFC documents almost immediately pay for the overhead.
Maybe more surprisingly, I myself am a team of two when I write a piece of code, then go work on something else, and come back three months later to fix a bug or implement a new feature. I am always very grateful for the tests or comments I added three months ago, because they will reliably prevent bugs or unintended behaviour changes.
Note that every production code base will be touched by two or more people. This happens either when the sole developer has forgotten the details and is effectively reborn as a new contributor, or when the team composition changes over time as old team members leave and new team members get onboarded.
What about Hackweeks or Hackathons, you ask? Isn’t it a waste of time to write tests and do code reviews when your Hackweek demo is only three days away? On the one hand, yes, I agree that good teams of three or four can maintain shared state over the course of a week even without tests or documentation or code review. On the other hand, how often have we broken the code base just minutes before the final demo… can we somehow get the best of both worlds, quality and velocity?
Engineering quality as a skill
Mastering engineering quality is a skill. And just like most programmers don’t master complex algorithms or understand the transaction semantics of distributed databases without hard work, it takes time and effort to understand what makes code maintainable or easy to operate. The reward for this effort is a toolbox of mental models, tools, and patterns that — I argue — let you write high-quality code at almost the same velocity as the piece of write-only code you’d otherwise produce. Note that this won’t be true on day one of your learning journey; you’ll hate your code reviewer for comment number 57 on some supposedly silly detail, and you’ll “waste” a lot of time refactoring things, or fixing grammar issues in the documentation, or reconsidering the field naming of that API (again!). You will reap the rewards later, trust me.
To summarise, I don’t subscribe to the common excuse, “we need to trade-off between quality and velocity!”. Engineers can acquire the skills needed to naturally produce high-quality code bases; this is a learning process which takes time, effort, mentoring, and attention to detail. It will also pay for itself.
Learning resources
A few highlights from my reading list:
