A God Module, you mutter, with the disgust of a person who has read the book.

So you do what twenty-five years of professional habit demand. You refactor it. You don’t do it by hand, of course — you have the agent do it, under your supervision, with Uncle Bob whispering in your other ear. You break the file apart. You name things properly. You introduce a few small, pragmatic abstractions. You document the architecture in Markdown. The result reads as prose. It is not over-engineered. It is clean, in the canonical sense.

You feel good. You go to add the next feature.

And the agent stumbles.

The same model that one-shot refactored six thousand lines of slop spaghetti the previous afternoon now cannot find its own utility classes. It hallucinates function arguments. It reinvents code that already exists, two folders away, with a name that almost rhymes with the one the agent just made up. You watch this happen, and you realize, slowly, that something is broken. It is not the model — the model didn’t get worse in twelve hours. It is the codebase. The very act of cleaning it up has made it harder for the agent to navigate.

And then, you realize what’s actually broken is your instinct to refactor. It is the foundation that instinct stood on. It is the entire premise of the book on your shelf.

The Reader Axiom — that code is read far more often than it is written, so optimize for the reader — has been quietly invalidated. Most of what we built on top of it was QWERTY.

The QWERTY keyboard layout was designed in the 1870s to slow typists down, so the mechanical arms in early typewriters wouldn’t jam. The constraint vanished a century ago. The layout did not. We’ve spent 150 years training people on a workaround for a problem that no longer exists, and calling it “how to type”.

Most of Clean Code is like QWERTY. The mechanical typewriter is the human brain; the arms are working memory; the workaround is a thousand small disciplines designed to keep the brain from jamming when it tries to hold a five-thousand-line file in mind. Small functions, meaningful names, careful formatting, intention-revealing structure. The patterns persist because we taught them — not because they were ever about the underlying activity. They were always about the human reader.

Robert Martin’s book wasn’t wrong. It was correctly identifying the typewriter, the arms, and the jam, and prescribing layouts that reduced jams. The book held for forty years because the constraint held for forty years. The next reader was always a junior engineer, scrolling through that five-thousand-line file in a terminal at 2 a.m., trying to figure out why production is on fire. We owed her clarity. We mostly delivered.

The next reader is no longer her. The next reader has a 1M context window, no opinions about formatting, and reads the file in 800 milliseconds. It does not jam.

Twenty-five years writing code, two writing it with agents at my elbow. Sample size of codebases where I’ve watched the Reader Axiom break: enough to have stopped treating it as bad luck. There is no peer-reviewed paper for this — yet — but the pattern is visible enough that I have stopped trying to refactor my way out of it.

Take a deep breath. Most of what we called engineering ‘best practice’ is up for inspection.

Sorting the canon

The interesting question isn’t whether the Reader Axiom has expired. It has. The interesting question is which of our practices were QWERTY all along — workarounds for a constraint that no longer holds — and which were doing structural work the whole time.

DRY is the cleanest example. Every senior engineer can recite it: don’t repeat yourself. Every senior engineer also knows DRY is a balancing act. Too DRY and you get baroque inheritance hierarchies named AbstractFactoryStrategyVisitor. Not DRY enough and you get bug-multiplying brittleness. The balance was always governed by a hidden term: the cost of changing things in lockstep across the codebase. When that cost is human and high, DRY wins. When that cost approaches zero, DRY loses its argument.

A SaaS company I know spent the better part of a quarter building a polished internal design system. Tokens, primitives, smart components, the works. The reason — without it, every minor design tweak required hunting down forty-three slight variations of the date picker. With the design system, you tweak in one place and inherit everywhere.

Then they pointed an agent at the codebase. The agent, faced with a need for a date picker, did what agents do. It built one. From scratch. Inline. Beautifully styled. Using none of the company’s design system, which it had been told about in three different places.

Under the old constraint, that agent’s behavior would have been a catastrophe — forty-three slight variations of the date picker, and any global design tweak now requires forty-three little surgeries. Under the new constraint, the cost of that global tweak is ten minutes of agent time. The case for the design system is no longer that humans will pay for it later. The case has to be made on different grounds, or it can’t be made at all.

You can run the same exercise across the rest of the canon. Small functions: QWERTY. Cutting a function into ten-line pieces was a chunking workaround for human working memory, which holds about seven items at a time and overflows on anything longer. The agent has no such ceiling, and reads the whole file in one breath. The fix was for our jam, not the code’s. Meaningful names: QWERTY. The agent is happy with processStuff_v2_FINAL_actually_real. SOLID, design patterns, careful formatting — every rule that was about helping a human chunk meaning loses most of its weight. They are still useful at the human-review boundary. They are no longer load-bearing.

What gets promoted is the half of the discipline that was never QWERTY in the first place — the practices whose load came from the runtime, not the reader. API-first design. End-to-end testing. CI/CD. Observability. Property-based testing. Contracts, invariants, machine-checkable assertions. These were always doing structural work, and the Reader Axiom expiring doesn’t touch them. If anything, it makes them more important: when nobody reads the code, the contracts and the tests are the only things keeping the system honest.

What dies entirely is the third pile — the practices that existed to coordinate teams of humans. These solved problems that don’t exist in the same shape when half the work is being done by something that doesn’t get tired, doesn’t bikeshed, and doesn’t need a daily standup. The team is something else now, and the rituals that managed it are vestigial.

The surviving rules were the ones about intent, verification, contracts, or safety. The rest was QWERTY.

What this reveals

Once you start running practices through the QWERTY filter, the bigger picture is uncomfortable.

Most software engineering “best practices” were never about software. They were cognitive scaffolding for the humans holding the code. Most of what we taught engineers was never engineering — it was ergonomics dressed up in engineering vocabulary.

The AI age won’t kill software engineering. It will reveal that half of it was always something else.

That single reframing explains a lot of things that used to be confusing. Why a junior engineer who was rigorous about formatting could ship correct systems and a principal engineer who couldn’t be bothered with naming conventions could too. Why pair programming was transformative on some teams and felt anachronistic on others within five years of the same generation. Why every company that adopted SOLID at the C-suite level produced two camps of engineers, one swearing by it and one quietly working around it. The practices weren’t failing or succeeding on their merits. They were succeeding when they happened to fit the cognitive ergonomics of the people doing the work, and failing when they didn’t.

The discipline never had a clean way to talk about that, so it called the ergonomics “engineering” and went on. The AI age is the first time the labels have been forced apart, because half the practices stop applying when the entity reading the code doesn’t have the cognitive constraint they were designed around.

What survives is the engineering. Which, it turns out, is a much smaller and harder thing than the canon implied.

Clean Code, rederived

There is a comfortable reading of all this — the agent has it covered, stop messing with the code — and it is wrong. Left alone, an agent will gleefully ship you a twelve-thousand-line God Module with three slightly different date formatters and a serializer named format2. Sure, it can refactor — modern agentic harnesses ship with refactoring as a built-in step, and an agent will gladly carve a four-hundred-line function into ten neat forty-line ones if you ask. The problem isn’t whether it refactors. The problem is calibration. Every byte of its training data was written under the old constraint — Clean Code, the tutorials that reproduced it, forty years of code structured for a human reader. The post-QWERTY corpus is a few thousand blog posts from the last two years, written by people like me working it out in real codebases. My take here is one of those.

The work has not gone away. It has changed shape.

If QWERTY was the layout we kept after the jam disappeared, the question now is what you’d design if you sat down at the keyboard fresh, with the next reader at your elbow. The new orthodoxy — the one I now hand my agents in AGENTS.md, with a refactoring skill alongside — looks, file by file, like the inverse of what the book on the shelf prescribes:

• Vertical slices, not horizontal layers. All the logic for a single entity — type definition, database mapping, validator, serializer, output formatter, factory, repository, service interface, local utility class, DI wiring — lives in one file. The agent never has to pick between ten possible homes for a function it is about to write. Pulling the right context out of a six-thousand-line file is trivial. Guessing wrong about which of ten files to grep is what produces the second date formatter.
• One file per concept, up to about ten thousand lines. Big enough to swallow a whole entity-shaped slice. Small enough that a million-token context window inhales it without breaking stride. The old two thousand lines is a smell rule was a constraint on human scrolling. The new ceiling is five times higher, and it’s a constraint on the model’s context. Different organ, different limit.
• Machine-checkable seams, not pretty ones. Contracts, types, tests at the module boundary. The agent respects a failing assertion. It does not respect a comment that says please don’t add a fourth implementation of date formatting. Nor should it have to.

None of this means the old disciplines disappear entirely. I still ask my agents for meaningful names and decent formatting — the small ergonomic moves that keep things bearable at the human-review boundary. They have been demoted, not deleted. Soft preferences, not hard rules.

This is not laissez-faire. It is more deliberate, not less. You are still designing the codebase from first principles. You are just designing it for a different reader.

Pushback

The objections write themselves.

“But humans still read code. When production breaks at 2 a.m., you can’t ask the agent to debug itself.”

Sure you can, Strawman Sam.. but I get your point. The demoted disciplines exist for exactly that 2 a.m. session. They just no longer govern the whole codebase. What has changed is the ratio. The vast majority of code-touching activity has shifted from read-then-modify to spec-then-regenerate or test-then-verify. And when the 2 a.m. session arrives, the thing you actually need to read is the test that failed, the contract that was violated, or the diff between two agent runs — not the function body.

“This is just an excuse to write sloppy code.”

It is not. Machine-checkable seams are harder to install than cosmetic ones are to enforce. Property-based testing is harder than naming. Designing a bounded interface the agent cannot accidentally misimplement is a more rigorous kind of work than refactoring processOrder into validateOrder + persistOrder + emitOrderEvent. What gets stripped away is cosmetic rigor. What remains is the actual kind.

“You’re describing a transitional moment. In five years the agents will be reliable enough that none of this matters.”

Maybe. Maybe even probably. But the transition is the rest of our careers, and assuming a problem will resolve itself eventually is exactly the cognitive move that produced every legacy codebase any of us has had to dig out of. We are in the transition. The transition is where the work is.

The objections are not silly. They are written from inside the old constraint — and the old constraint is what changed.

I haven’t refactored that codebase since. The God Module is, of course, gone — Uncle Bob and I made sure of that. But the parts I’d have rewritten next, on instinct, on autopilot, because something in me said this is too messy — those parts are still standing. The agent has been navigating them like it owns the place. We get along now.

I keep the book on the shelf. I just stopped reaching for it before I refactor.

First with naming conventions — BEM, SMACSS, OOCSS — bolting structure onto a language that didn’t enforce it. Then with build tools — CSS Modules, styled-components, Emotion — abandoning stylesheets entirely in favor of runtime JavaScript. And finally with Tailwind, which solved the collision problem by nuking the abstraction layer altogether, scattering flex items-center justify-between px-4 py-2 bg-white rounded-lg shadow-md hover:shadow-lg transition-shadow duration-200 across every <div> in the codebase and calling it progress.

Every one of these was a rational response to a real problem. The cascade was unwieldy at scale. Naming was fragile. Global stylesheets did break silently when teams grew. Each layer of workaround was a cast on a bone that was genuinely fractured — and at the time, you were right to put one on.

The bone healed years ago. The casts are still on. The limb underneath has begun to atrophy.

What healed it is not a single feature. It is a quiet evolution. @layer gives you explicit control over cascade priority — specificity wars, solved. @scope contains styles to a DOM subtree without any naming convention, build tool, or runtime — collisions, structurally impossible. @property lets you register typed, inheritable custom properties with defaults, turning the cascade into something close to a contextual type system. :has() lets CSS inspect the contents and relationships of elements, eliminating most presentational classes. Native nesting. Container queries. @starting-style for entry and exit transitions. Most of these shipped in the last two years. None existed in practical cross-browser form five years ago. Together, these form a new paradigm.

Call it Platform-First CSS. After fifteen years of frameworks built to patch the platform, here is one that runs on it. You don’t reach past CSS any more. You reach into it.

I have been writing CSS since it first landed in Netscape Navigator 4.0 in 1997 — coming up on three decades. Eight years on preprocessors. Five on the various pre-utility workaround layers. Four on Tailwind. Every one of these casts has been on my arm at some point. Every one came off again.

So — three casts, three layers of workaround, one underlying paradigm. Let’s take them off, one at a time.

The naming-convention cast

In 2013 I had a brief love affair with SMACSS. The first weekend was almost zen — the conventions were thoughtful, the philosophy was clearly onto something, and the part of my brain that had been holding the cascade in its context finally got to relax for a few hours. Within weeks however, the housekeeping was eating the project. CSS variables didn’t exist yet, so the modifier classes multiplied: .button--primary, .alert--primary, .badge--primary, each one duplicating the same color value in a slightly different declaration. Adding SASS rescued the ergonomics, but felt a bit like fixing your bike by throwing it on the back of a truck and driving instead. The discipline of remembering which prefix went with which module never became automatic, and SMACSS never quite earned a place in my default toolkit.

That was twelve years ago. The thing SMACSS (and BEM and OOCSS) were trying to do — give every selector a bounded address so it couldn’t collide with another component’s styles — is now what @scope does, but enforced by the parser instead of by a twenty-page convention document.

@layer components {
  @scope (.card) {
    :scope { background: var(--surface); padding: var(--space-m); }
    .title { font-size: var(--text-lg); font-weight: 600; }
    .body  { line-height: 1.6; }
  }
}

Here, .title inside .card and .title inside any other component are completely separate selectors. There is no .card__title. There is no naming convention. There is no slow accrual of compound class names that read like German nouns. You can call your inner elements .title and .body and .actions across the entire codebase, and the browser will keep them apart for you.

And not just within one team’s codebase. Two teams in different parts of a large organization can both define .actions inside their own scopes without coordinating, without sharing a naming ledger, and without anyone owning a global compatibility table. This is the thing that finally lets no-build vanilla CSS scale past the two-pizza team.

Conventions are not architecture. @scope is architecture.

The runtime cast

Throughout my career, different companies have tried different methods for taming the cascade — CSS-in-JS, styled-components, hand-rolled variations on CSS Modules. Each one bought us a ticket out of !important hell, and each one paid for it with our ability to keep a consistent style across the site over time. The styles lived in the components, which meant the design system lived in the components — which meant the design system was now duplicated across every component file, drifting in tiny ways from one PR to the next.

I realized it during a theme-switch implementation. To turn dark mode on, the codebase needed a context provider, a hook in every styled-component file, and a re-render of every leaf node so the new theme prop could trickle down to the color declarations. To me, this amount of structural housekeeping for something so trivial was unacceptable: in my mind, all it should have needed was an attribute on a <section> element.

[data-theme="dark"] {
  --surface: #1a1a1a;
  --on-surface: #e5e5e5;
}

Wrap any subtree in <section data-theme="dark"> and every component inside it adapts. No prop drilling. No context provider. No re-render. The cascade does what it has always done — it passes values down the tree — and you just give it better values to pass. Once @property lets you type the color tokens, the theme switch can also transition smoothly, because the browser knows the values it is interpolating between are colors. An entire layer of React state plumbing collapses into an HTML attribute and a CSS rule.

Styles handle their own contexts again. Components stop pretending to be stylesheets. Separation of concerns, restored.

The utility cast

I never liked Tailwind. The syntax is ugly. It is a regression to the era of <FONT> tags and inline styles, dressed in a modern build pipeline. It takes a perfectly valid idea — single-purpose utility classes — and pushes it well past the point where the idea was useful.

My breaking point was the official launch of the JIT compiler. The pitch was that the new compiler would solve the bundle-size problem. In the demo, the build took twenty seconds. The resulting dev build was twelve megabytes.

To get back to a sane production bundle, you needed tree-shaking, content scanning, a config file that needs its own documentation site, and the patience to debug why your dynamic class names had silently vanished from the build. None of that complexity existed before Tailwind. The problem it was solving did not exist before Tailwind. The framework multiplied class names by every breakpoint, every state, every variant; the compiler then had to subtract them back out. The plumbing needed to fix the framework was bigger than the framework.

Take this cast off and you find that the limb works. It was the cast that was always clumsy — slow to bend, indifferent to context, full of ways to chafe. The longer it has been on, the harder it is to remember what writing CSS without one used to feel like.

@layer components {
  @scope (button[data-variant]) {
    :scope {
      padding: var(--space-s) var(--space-m);
      border-radius: var(--radius-m);
    }
    :scope[data-variant="primary"] { background: var(--color-primary); }
    :scope[data-variant="danger"]  { background: var(--color-danger); }
  }
}

Two scoped rules. Token-driven. No build step. The class on the button is data-variant="primary", which is the same number of bytes you would have spent on bg-primary text-white px-4 py-2 rounded, and the meaning lives in the markup instead of being scattered across half a dozen utility classes that the next person to touch this file will have to grep for.

A thin utility shelf still has a place — forty or fifty rules at most, derived from the same tokens, used to fill compositional gaps between components. The mortar between the bricks. The escape valve. Not the whole framework.

The pushback

The workarounds had reasons. The reasons deserve answers — not a wave of the hand.

“CSS is hard. Tailwind makes it easier.”

CSS was hard. The cascade was a minefield. Naming was a psychic discipline. Theming meant copying values everywhere or fighting a preprocessor’s variable scope. None of that is true now. With @scope, every component name is local. With @layer, every priority is explicit. With @property and a data- attribute, every theme switch is one line. The thing Tailwind was making easier no longer needs to be made easier. For the parts of CSS that many devs still find challenging – like positioning, alignment, or responsive media queries – there is no shame in going to Stephanie Eckles’ SmolCSS site and copying a utility class or six. That’s where utility classes shine.

“But the browser support — can I really use @scope and @property in production?”

Yes. As of May 2026, global support sits at 95.4% for @layer, 91.1% for @scope, 94.7% for @property, 94.3% for :has(), and 91.2% for @starting-style. These are not bleeding-edge numbers. They are baseline-2024, with eighteen months’ safety margin.

And one more honorable mention. Native @mixin rules landed in Chrome Canary last year. With a little luck, the last feature SASS still genuinely offered will be part of the platform itself in the not-too-distant future.

“What about animations? CSS-in-JS won partly because React gave us animation power that pure CSS didn’t have — keyframe choreography, spring physics, FLIP transitions.”

True, for a while. CSS keyframes caught up in 2016. The linear() easing function landed in late 2023 — spring physics in pure CSS, no library. View Transitions have been broadly available since 2025, handling FLIP-style animations natively. Most of what required Framer Motion or react-spring is now a stylesheet.

And when an animation genuinely has to be driven by JavaScript — interactive scrubbing, gestures, runtime physics — the integration point is one line: element.style.setProperty('--x', value). JavaScript pokes the cascade. The cascade does the rest. No stylesheet inside the component required.

“My team already knows BEM / Tailwind / styled-components. Switching is expensive.”

Knowing how to walk on crutches is not a transferable skill once the cast is off. The investment your team made in BEM was in remembering a convention. The parser does that work now. The investment in Tailwind was in memorizing thousands of utility class names; the platform provides what those classes were emulating. The cost of switching is non-zero, but it is paid once. The cost of not switching is paid every quarter, in the form of a build pipeline that needs care, a bundle size that needs trimming, and a design system that lives in twelve places at once.

Platform-First CSS is not a framework. There is no npm install, no config file, and no build step, though you can add one if you want file splitting or minification. Your choice, not a requirement. Platform-First CSS is an architectural pattern: the layer stack as the spine, scopes as the boundaries, typed properties as the type system, :has() and container queries as the relational and dimensional primitives. The composition primitive — native @mixin — is waiting in the wings. You can implement it hand-rolled. You can implement it using a kit. The paradigm is the platform itself.

It does not ask you to unlearn CSS. It asks you to stop fighting the cascade and start declaring it with intent. It asks you to use the CSS that actually exists today, instead of the CSS you learned to work around in 2015.

The cast is off. The limb is healed. We developers just need to use it again.

Time to start fresh and begin building a brand new system! One that is clean and modern. Version 2.0 we’ll call it. We will learn from our mistakes and get it right with an all new team.

This time it’ll be different.

The Greenfield-Bedlam Cycle

Take a deep breath.

That tangled codebase you’re looking at started its life with similar aspirations. And then reality hit: a quick fix here, a compromise there, some over-eager abstraction in the heat of the moment, and before long, it’s death by a thousand corner cuts.

With stakeholders to please and deadlines to meet, the technical debt piles up, until all that remains of the original architecture is a chalk outline in the rough shape of a strategy design pattern.

Once a codebase has been through the grinder of business for a fiscal year or two, the debt can become so expensive that a certain class of organization (that rhymes with schmenterprise) would rather just send it adrift on an ice floe and start over from scratch.

I call it the Greenfield-Bedlam Cycle of enterprise software development; when a large enterprise keeps building the same software solution over and over, only to have it become a nightmare of incalculable risk within months of deployment. When this happens, the old solution is scrapped and the cycle starts over with a brand new Greenfield project.

Even in lean organizations with stronger technical vision, I have encountered the view that non-trivial codebases cannot be kept clean and maintainable over longer timeframes. At least not in fast-evolving fields like front end web development, where the same framework library meta-framework will happily reinvent itself five times in ten years, each time creating a trail of dead remains of legacy code scattered across the web.

You can’t blame someone for having a cynical stance on the longevity of things when the very house they live in was built on quicksand.

Confronting The Messy Reality

How do we break the Greenfield-Bedlam Cycle? Can we somehow stop the atrophy of our codebases and create software solutions that last longer - much longer - and that remains functional, maintainable, and extensible for years or decades, without sacrificing development speed or relying on mythical 10x developers? And can we achieve this not just occasionally by happy accident, but methodically, repeatably?

I believe so, and the key to unlocking this power is acknowledging the imperfections of technology and developers, and the messy reality that your code will meet once it hits production. As a developer or software architect, you cannot opt out of reality, so you have to design around it.

Messy Reality Number 1: Requirements change

All project requirements are based on assumptions and limited information. In a matter of hours, assumptions can be invalidated or leadership priorities can change. Perhaps you simply encounter overwhelming success and need to scale beyond your wildest projections.

How would you change your design to face the reality that requirements could change at any point in almost any way?

Messy Reality Number 2: External circumstances change

Any new codebase is designed based on a version of reality that will not exist in 18 months. Technological innovation could make part of your solution obsolete, a competitor could launch a killer app that pulls the rug out from under your product, security vulnerabilities may be uncovered, or dependent libraries are abandoned by their maintainers, forcing you to replace them.

In short: Reality drifts

How would you change your design to face the reality that almost any technology it uses could require replacement on short notice?

Messy Reality Number 3: Mistakes are made

Even a stack of mind-boggling complexity can be maintainable by a highly skilled developer with in-depth knowledge of the tech, the domain, the patterns and paradigms. That person could never have an ‘off’ day; and they would always be given all the time and resources they need. Does that sound like the world of enterprise? I have it on good authority that it’s not the world of FAANG either.

In all likelihood, the developer assigned to work on your stack on a given day is going to be on a deadline or unfamiliar with some part of the domain or tech. They might be lazy (in the “move fast and break things” sense of the word), or just having a bad day. A lot of the developers who are going to work on your codebase in 18 months haven’t even been hired yet, and some are still in school or interviewing for their first consulting job.

The fact is, your code is going to see some hasty workarounds in its life, and not even the most meticulously designed software architecture survives first contact with a junior developer. That is, not unless it was built to adapt and endure – to resist bad changes and even self-heal over time.

How would you change your design to face the reality that the developers maintaining your solution will be making mistakes like they’re going out of fashion?

Principles of long-lived software design

How do we architect systems to survive and even thrive in a messy reality?

Principle 1: Know the developers

“People are part of the system. The design should match the user’s experience, expectations, and mental models.”

~ Principles of computer system design: an introduction

To achieve longevity in our solutions, we must consider the skill and time constraints of the end users (developers/maintainers) and design a system with the largest-possible Pit of Success for the average developer to stumble towards.

This often means “killing your darlings” by meeting the developers where they are, not where you wish they were. There could be a significant skill gap between where the team is today and where they need to be to maintain the system you’re proposing. Few companies will invest in a comprehensive training program to not only re-train your current developers, but also bring all future hires up to speed – including after you leave or get promoted to senior management?

Even if it breaks your heart; that cool technology you like probably has to go.

Knowing the developers can also mean creating frameworks or abstractions that remove boilerplate and flatten the learning curve, or relying on patterns and even naming conventions that are already familiar to the devs.

In 2014, I had to build a frontend framework for a team of backend developers, and rather than try to convert them all to JavaScript enthusiasts, I created an HTMX-like markup syntax and async DOM manipulation component allowing them to build and maintain interactive frontend features without ever having to leave their familiar C#.

Finally, ‘knowing the developers’ means helping the developers know. Supporting their daily workflow by investing in writing rich documentation, templates and developer tooling, and spending time evangelizing the system, will reduce the friction of working on the system, and pay dividends in the long run.

You want both existing and future team members to feel intuitively familiar going into the codebase. This will allow them to make robust changes from day one.

Principle 2: Keep It Simple

Designing for longevity might sound like advocating for highly abstracted Ravioli Code, but that is not the case. For instance, in the early phases of development, you can safely assume that each iteration will be so different that any abstraction you built in the previous one will have to be scrapped anyway. The pragmatic way to design for such drastic change is to cobble together an MVP with bash scripts and bubble gum, since the next version will start from scratch either way.

Any complex system that works is invariably found to have evolved from a simple system that worked. The inverse proposition also appears to be true: A complex system designed from scratch never works and cannot be made to work. You have to start over, beginning with a working simple system.

Gall’s Law

As a rule, abstractions should be avoided until they can pay for themselves by taming parts of the code which have become unwieldy. Pragmatic, well-timed abstraction is beneficial, whereas premature abstraction violates Gall’s Law and leads to broken software.

Start Simple. You Ain’t Gonna Need It.

Principle 3: Design for change

Try to ensure that the systems you design are easy to change.

Naming things

Make the code - and repo structure - intuitive, adhering to the Principle of Least Surprise. If a developer doesn’t find the natural place to apply a change in the first or second place they look, they might just come up with a creative solution instead. Now you have two places where authorization rules are defined. Next week it could be three. Every ‘surprise’ in your design will attract code rot over time.

Encapsulation

Identify natural domain boundaries and encapsulate them with clear contracts. Rather than a technical boundary defined by microservice gateways and deployment bundles, or an organizational boundary defined by lines of management, a ‘domain boundary’ encapsulates a family of concepts which are likely to change together because they are intrinsically coupled, such as Users and UserProfiles.

Encapsulation by good domain boundaries simplifies future refactoring and aligns with real world aspects of your business/product, which are naturally long-lived.

The paved road

Prefer the well established stack over the ‘best’ one, since the 75% ‘batteries included’ solution that just works beats the 100% solution that requires constant tinkering because the stack is unstable and the developer ecosystem doesn’t exist yet. The exception is when you’re building systems at massive scale, where the absolute value of even a small incremental improvement can dramatically outweigh the cost of a team tinkering away on the 100% solution.

For open source dependencies, consider the size of the community and the number of contributors. If the project is maintained by a single person, it makes for a risky dependency. How frequently are major versions released? That is how often breaking changes are introduced. Do the maintainers keep updating and patching older versions, or will your team be forced to migrate to whole new versions every year to address unpatched security vulnerabilities?

When it comes to cloud platforms and application frameworks, these are load-bearing structures for your application, and you should choose the most stable and well supported option available. When it comes to libraries and services, you can afford to be more experimental as long as you take the necessary precautions, which brings us to…

Loose coupling

Keep systems loosely coupled: if you have fifty services all sending their logs to some 3rd party analytics tool, then consider creating a custom facade library to wrap all communication with the 3rd party tool. That way, when the day comes that the company changes logging tools (a safe bet), you only have to change the facade library in one place rather than all fifty services.

…but be pragmatic: If you can’t achieve looser coupling without adding a ton of complexity (stomping all over the KISS principle), you are probably better off accepting a bit of tight coupling. Certain key decisions, such as your choice of cloud provider, are one way doors with no easy way out, and while this may feel risky, it can bring great benefits; and one should never trade ten birds in the hand for one in the bush.

Open standards

Make sure that all critical business data is stored and accessible over open or de facto standards. ODBC is an open standard, as is Apache Arrow, whereas AWS S3 is an example of a defacto standard.

Stay away from closed proprietary data formats to prevent data lock-in and maximise the chances of future tool integrations just working out of the box.

Go build things to last

“What are you waiting for?! DO IT! JUST DO IT! YES, YOU CAN! JUST DO IT! If you’re tired of starting over, STOP GIVING UP!”

~ Shia LaBeouf, possibly referring to this article

Once you begin thinking of code in terms of longevity, it changes your approach to most aspects of software development.

The value of good documentation skyrockets when code needs to outlive multiple teams of maintainers. You still take on tech debt, but you may determine that some classes of tech debt (e.g. a quick and dirty one-off script or MVP) are acceptable while others (unintuitive naming or convention-breaking folder structures) are not. Your policies and preconceptions about automated tests, encapsulation, etc. – all need to be revisited when designing systems to stay in production for a decade or longer.

In return for this, however, you get a codebase that actively resists bad code; that neatly allows for innovation or changing requirements; a codebase that stays lean while maintaining high developer productivity for years – and which doesn’t require a costly bottom-up rebuild for every 2-3 years.

The result is faster development, higher quality, happier developers, and all of that at a significantly lower total cost of ownership.

Something I could one day nail to my wall if and when I ever get around to launching a startup of my own.

I didn’t expect it to come out as poetry though.

Start with a monolith

Start in the cloud

Start with a stack you know

Lean in for the KISS

 

DevOps is rocket fuel

Tests give you speed

Stay off the bleeding edge

This is your creed

 

Start with an MVP

Forget about scale

Look for that market fit

Make that first sale

 

Obsess over customers

Know why they click

Shorten your feedback loop

Don’t be a dick

 

Don’t chase that VC yet

Start with no dough

Launch early and often

Then pitch once you grow

 

And when you have…

 

Your culture can get out of hand

like a manifesto turned poem

Don’t hire what you cannot coach

Grow slow… or grow home

I will free admit that this is aggressively self-indulgent, pompous even… but it’s not wrong.

Hiring the right people

If I am going hiking, I don’t want the person who has memorized all the different hardening grades in the alloys of his pocket knife. I want the person who could start a fire in the dark in four different ways with nothing but a rock and pinecone. And in two more ways if the pinecone is wet.

Apply that to software and you have a surprisingly powerful recruiting method. Personally, in 10 years of hiring, I have not regretted a single hiring decision I made in this way.

(This is not the article to get into the details of hiring developers, but if you are interested, feel free to ask me. You may regret asking though – I can talk for hours about recruiting.)

Giving them what they need

Par for the course is powerful hardware, choose-your-own-keyboard, and the occasional conference ticket; but two essential things that top developers need to be both happy and highly productive, is clear direction and trust.

Once developers understand the “why” behind a high level requirement and are trusted with the details, they are free to explore and implement new and creative solutions. Such solutions may arrive at the goal in unconventional ways, but they almost always arrive both faster and better than anticipated by stakeholders or architects.

Getting out of the way

Obviously, don’t micromanage, but take it a step further and eliminate any and all interruptions and dependencies that get in the way of the work or pull the developer out of their productive ‘flow’. By my count, even the smallest interruption costs at least 30 minutes of productivity, in part due to the context switch itself but mainly from the process of slowly getting back into the flow of coding.

As for dependencies, any process that requires getting a response from a person outside the immediate team introduces a perfect storm of context switching, busy-waiting, and in some case even anxiety; these are people who may very well have spent 10,000 hours learning to code alone in front of a computer: a lot of them don’t like talking to people, let alone people they don’t know.

Finally, hands-off management is not ears-off management. Every team has needs which evolve over time, and as a leader your job is to listen and provide, whether that means coaching them, buying them nerf guns, or fighting off stakeholders when they come bearing gifts of this week’s feature creep (and it is always feature creep).

1. The willingness to make mistakes. Small mistakes can be accepted as the cost of doing business, bigger ones can be automatically detected and remediated in real time. Velocity is gained through automation and no-blame culture.
2. The number of hours per week where a state of high-productivity ‘flow’ can be achieved. Flow can only happen where developers have uninterrupted time and clarity of goals. Velocity is gained through hands-off leadership.
3. The ability to make decisions in real time, without having to ask permission or coordinate with external teams. Velocity is gained through trust, transparency and architectural decoupling.

In short: Automation, No-blame culture, Hands-off leadership, Trust, Transparency, and Architectural decoupling.

Tenets of Lean, but boogeymen in the typical enterprise.