From an individual API producer’s perspective, adherence to an enterprise company’s design style guide may seem puzzling. “Why do we have to learn these naming conventions?” they’ll ask. Other questions include, “What difference does our style of versioning make?” or “Why can’t we use the authentication scheme that worked at my previous company?”
At the end of 2019, I did a series of “Back to Basics” roadshows for my day job. According to various surveys, the average developer tenure at any company is between one and two years. My goal, through the roadshows, was to re-establish the principles that have guided our five-year-old program. I’ve used urban planning stories before, whether that is Brazillian Favelas or Paris’s tree-lined boulevards. To justify the need for enterprise standards for a degree of design consistency, I used a traffic regulation analogy.
I was reminded of it because of the most recent Postlight podcast, “Restricting Freedom for More Freedom: On The Parallels Between Wearing a Mask and Regulating Tech”. In that show, hosts Paul Ford and Rich Ziade discuss people treating mask requirements during Covid-19 as a violation of constitutional rights (spoiler: they’re not).
Sometimes inconveniencing the individual is the best for the larger group. That goes for whether we’re talking about masks, software governance, or traffic. Below a snippet of my argument from that “Back to Basics” deck.
Modern software architecture is complex
John Ousterhout, in his book “A Philosophy of Software Design”, defines complexity as:
“-anything related to the structure of a software system that makes it hard to understand and modify the system.”
In other words, a barrier to the kind of business agility that we crave, that is needed to win in competitive marketplaces, is how hard our architectures are to grok.
Message Passing Hides Complexity Behind an Interface
Message passing is a means of abstracting complexity and hiding behind an interface.
That abstraction allows programmers to work on a system without being exposed to all a system’s complexity at once. An API is a simplified view that omits unimportant details (or at least those details unimportant to the API’s consumer). It makes it easier for us to think about and get stuff done in complex environments.
“Going Faster” and “High Quality” Are Not Diametrically Opposed
“Going faster” is not a matter of getting rid of the rules. Martin Fowler, elegantly states to the contrary, that this is a false trade-off. In his piece, “Is High Quality Software Worth the Cost?” he outlines how quality efforts, over time, translate to great speed for the entire system over any individual’s speed.
Quality Design is a Financial Imperative
Low-quality design, while quick to make, incurs a lifetime tax. Maintenance is harder, requires additional overhead, and compares less favorably in the marketplace. Quality is not a moral argument, something that makes our inner artisan feel good. Quality design is a financial imperative to increase our software return on investment.
“The Key to Writing Less code and causing less rework is to write better abstractions” - Eric Elliot, distributed systems expert and author
We Need Continual Renewal and Reflection on What Quality Means for Us
That is why it is essential that each of us, whether we are product managers, architects, or engineering leads, continually renew our understanding and application of basic core principles.
A garden is not something that you plant in the spring and wander away from. The ability to reap what was sown requires constant attention and care. We have to rededicate ourselves to executing on the fundamental, basic things before overcoming complexity is possible.
Our Road is Shared
And the most basic thing, the first principle - the one to remember if you remember nothing else - is that we’re in this together.
When there is only one car on the road, then the fastest way to get from point A to B is to ignore all speed limits, go whichever way they want on one-way roads, and view all traffic signage as optional. From their perspective, an individual team will wail and gnash their teeth at how much faster they could get to production if they were only allowed to do whatever they want. Imagine the freedom(!!!)… for them.
However, there is not a single team. There are hundreds on their journeys, crisscrossing each other and going to and fro. Things like speed limits, lane markings, stop signs, and traffic signals are all there to move the most people to the greatest number of places, safely. We exist within a system. The road we travel is shared between us. If we are going to arrive, it will be through minor, in-the-moment, inconveniences made for the larger, more-long-lasting, good of all.