The Readable Codebase

On legibility as the scarce resource in the AI era.

• Begun
• February 2026
• Finished
• April 2026
• Length
• ≈ 1,957 words · 9 min

The Score #

A musical score is the strangest artefact in the cultural canon. A single document, composed once, in solitude, that becomes a living instruction set for hundreds of performers across centuries — each of whom must open the page and immediately understand not only what notes to play but what the composer meant by writing them in that order. The score is not the music. The music happens when human beings interpret the marks. The score is the medium through which intent survives translation, the document whose entire job is to be read by someone other than the person who wrote it, the artefact whose value is measured almost entirely by how cleanly its meaning travels from one mind into another.

Software has spent forty years pretending it is something else. We built our codebases as factories — measured in throughput, output, lines shipped, features delivered — and we rewarded the engineers who produced the most of it, fastest, regardless of whether anyone downstream could read what they made. The codebase as factory floor produced a generation of systems whose internal logic was knowable only to the original authors, only briefly, and only on a good day. The industry then built an elaborate apparatus of tribal knowledge, internal docs, onboarding programmes, and Slack archaeology to compensate for the fact that the source itself had stopped being legible somewhere around the second refactor.

That apparatus was always wasteful. But it was survivable, because the bottleneck was always the writing. A team of eight could produce only so much code in a quarter, and the limits of human typing speed acted as an unintentional governor on complexity. The codebase grew at roughly the rate the humans inside it could still hold in their heads.

That governor has now been removed.

The New Scarcity #

Competent code generation has dissolved, in under two years, the constraint that shaped every assumption about how software gets built. A pair of engineers with the right tooling can now produce in an afternoon what a six-person team used to produce in a sprint — not because the engineers got faster, but because typing is no longer the bottleneck. Anything is no longer the bottleneck, except the thing that always quietly was: the human capacity to understand what has been written. Production cost has collapsed. Comprehension cost has not.

The first-order consequence is obvious. The codebases of the next decade will be larger, denser, more abundant than anything before them, and most will collapse under their own weight inside eighteen months, because no human will be able to walk in and know what is going on. The second-order consequence is the interesting one. The codebases that survive — that compound rather than collapse — will not be the ones with the best AI assistance or the cleverest abstractions or the most aggressive automation. They will be the ones whose source is scored. Composed for readers. Written so that a product manager, a developer hired this morning, a cinema operator with a quarter of an engineering background, and an autonomous agent acting for any of them can open the same file and read the intent before they read the implementation.

The industry keeps mistaking this for a quality-of-life concern. Readable code used to be what senior engineers asked for when they wanted juniors to use better variable names. That framing is now dangerous. When a single engineer can summon ten thousand lines of plausible code before lunch, the cost of writing has dropped below the cost of reading, and the gap widens monthly. Writing code that explains itself to other humans — across roles, across seniority, across the line between people who write software and people who only operate it — is no longer a courtesy to colleagues. It is the substrate any codebase that intends to stay economically viable in the agentic era has to be built on. The scarce resource is not lines. It is legibility.

What the Score Encodes #

A score does not encode the sound. Anyone who has watched a violinist read Bach for the first time knows the marks are an instruction for how to think about a passage, not a recording of it. Dynamics, tempo, phrasing — interpretive cues, signals from the composer about what matters, what carries weight, what to listen for in your own hands. The score tells the reader what the writer was paying attention to.

Code can do this. Most of it doesn't.

A typed client method that reads client.sessions.list({ siteId, date }) is not merely clean the way an aesthetic preference is clean. It is scored. The shape of the method is a sentence — a verb acting on a domain object, parameterised by exactly the two things that matter, returning a value whose type is the same shape across every other endpoint in the system. A developer reading that line for the first time does not consult documentation, ask a colleague, run the code, or open a debugger. They have read the intent in the signature. The cost of comprehension is zero, because the writer paid it for them, in advance, by composing for a reader.

An error hierarchy that produces a RateLimitError

with a typed retryAfter

field is scored the same way. The error is not a string parsed from a response body, not a status code interpreted in three places by three engineers each making slightly different assumptions. It is an object whose presence in a catch block tells the next reader, in one line, both what went wrong and what to do about it. The recovery logic writes itself — not because the code is clever, but because the writer named the situation precisely enough that the name carries the meaning. Someone walking in six months later does not need to discover that the API uses HTTP 429 with a Retry-After

header in seconds-or-HTTP-date format. They need to know rate limits exist and there is an idiom for handling them. The score already told them.

This is the discipline. Not commenting more. Not writing prose explanations beside the implementation. Composing the implementation itself so the names, the types, the structure, the order of operations all collaborate to make the next reader's interpretation effortless. Every method signature is a line of the score. Every type definition is a marking. Every directory structure is the architecture of the page, telling the reader where to look first and what carries the melody.

The Cross-Role Test #

Cinema technology is the proving ground for this discipline, because cinema technology has no choice. The domain knowledge required to build a cinema platform is distributed across roles in a way almost no other industry replicates. The person who programmes films into a session holds a different mental model from the person who configures loyalty-tier rules, who holds a different model from the engineer building the seat-map component, who holds a different model from the accountant reconciling tax across territories, who holds a different model from the operator who opens the building in the morning and runs it until midnight. A booking flow is simultaneously a UI problem, an inventory problem, a tax problem, a payments problem, a concessions problem, a loyalty problem, and a real-estate problem — and the codebase that supports it has to be readable by anyone holding any one of those models, and increasingly by agents acting for any of them.

The horizontal-SaaS playbook handles this by hiding the domain behind a generic interface and asking every role to bend toward the abstraction. Cinema technology cannot afford that. The domain is too specific, the operations too varied, the cost of misreading too immediate — a misunderstood inventory state means an empty seat in a sold-out screening, or a double-sold seat in front of two paying customers, and there is no graceful failure mode for either. The codebase has to encode the domain precisely and legibly, in language the operator would recognise as their own. Sessions, not events. Held, not pending. Companion seat, not adjacent reserved. The names matter because the names are what let the engineer and the operator point at the same line of code and agree on what is happening.

A codebase composed this way reads, across roles, as a single document with a single voice. The product manager opens a file and recognises the vocabulary from the last operator interview. The engineer opens the same file and recognises the type contracts from the API docs. The operator, walked through it by either of them, recognises the model of their own building. The score is the same. The performers differ. The music — the operating cinema — happens when each of them plays their part against a document they can all read.

This is the territory the work I am building under the name Theatrical is being shaped to demonstrate: that the cinema-technology codebase composed for legibility outperforms the one composed for cleverness. The thesis is not that cinema needs better tools — that argument lives elsewhere. The thesis is that the tools cinema deploys over the next decade will be judged by a property the industry has not yet learned to measure: how cleanly their source reads to the humans, and now the agents, who have to live inside it.

The Industrial Argument #

None of this is an aesthetic preference. The score is not a stylistic choice on the composer's part; it is the mechanism by which an orchestra is possible at all. Strip it away and you do not get a freer ensemble — you get silence, or noise, depending on the temperament of the players. The same is true of a codebase. The legible one is not the prettier or the better-documented or the more pleasant codebase to work in. It is the only kind that survives an environment where production has become free and comprehension is the only thing standing between a company and irrelevance.

The codebases that compound over the next decade — that absorb new engineers, new product managers, new operators, new autonomous agents, without each onboarding extracting a tax on velocity — will be the ones whose authors understood early that writing software had quietly stopped being a writing problem and become a reading problem. The differential will not be subtle. From the outside it will look like one company shipping confidently into adjacent territory every quarter while another spends every quarter rediscovering what its own systems do. The first company will look lucky. It will not be lucky. It will have composed for readers from the beginning, paid the small upfront cost of scoring every line, and collected the compounding return on every change after.

The companies that get this right will dominate the industries where domain knowledge is distributed across roles, because those are the industries where the cost of illegibility is highest and a shared score is worth most. Cinema is one of them. Cinema is, in fact, the cleanest test case any of us are likely to meet — an operation where a programmer, an operator, an accountant, and a moviegoer all touch the same system inside a single transaction, and the codebase either holds together as a coherent document they can all read or it doesn't.

Coda #

A score is not finished when the composer puts down the pen. It is finished, and re-finished, every time a musician opens it and finds the meaning inside the marks intact. The composer's craft is measured, over the long arc, by how many performers across how many decades can pick up the same page and play. The engineering craft of the next era will be measured the same way. The codebases worth inheriting are the ones a stranger can open, on a Tuesday morning, and read like a sentence written for them — and only then will the music start.