Here’s what I keep hearing about AI, over and over, and it is so thoroughly baked into people’s assumptions that even folks who seem to understand AI and large language models eventually wander right back into it:
AI runs on a computer, so it must think and reason like a computer.
That is usually about the point somebody announces that we do not need to worry about making code readable for humans anymore.
AI is going to read all the code. AI is going to write all the code. Follow that argument far enough and apparently we will never, ever need to lift the hood again. The code will not need to be read by a human, and therefore it does not particularly matter how it is written. Readability and code quality are quaint relics soon to be buried in the past.
Meanwhile, over in Reality Land
The minute people start using lots of agents, hooking up MCPs, and building out their “harness,” everybody’s favorite buzzword of the moment, the codebase starts sprouting documentation like kudzu.
There is a CLAUDE.md, an AGENTS.md, this README and that README, instruction files tucked into every corner, and comments. So many comments.
I saw a Sass file the other day that looked as if somebody had written three essays and then, as a sort of administrative afterthought, added some styles. I wish I were joking.
There were at least three paragraphs of commentary for what amounted to fewer than ten rules. I have never seen that much explanation in a Sass file in my life, and I have seen some things.
Yet there it was.
AI was helping make the code, and we were carefully refining the comments so the AI could make sense of the code it was helping make.
Hmm. Anyone see the contradiction in the room?
Because the agents need it
Why are we providing AI with so much extra context? Why are AI-assisted codebases accumulating all this additional commentary? Why are we stuffing a Britannica’s worth of information around the code?
Because the agents need it.
They need the details living in engineers’ heads: the relationships between modules, the outside documentation, the history behind particular changes, the conventions nobody bothered to write down, and the meaning hidden across commits, tickets, comments, and years of accumulated decisions.
A human who has worked in the codebase may infer a great deal of that history.
An agent arriving cold often cannot.
That ought to tell us something.
Readable code, human and otherwise
One of the central ideas behind clean code is that code ought to be readable, understandable, and discoverable by another human being. A person should be able to look at a module and fairly quickly determine what level of abstraction they are working at, which details matter, what a function does, and where its responsibilities begin and end.
We make boundaries clear. We choose meaningful names. We try to make behavior predictable and dependencies comprehensible. We arrange the thing, or at least attempt to, so the next person does not need to conduct an archaeological dig every time they want to change a button.
Readable code does not have to be perfect. It does not have to be so exquisitely designed that the angels descend, inspect the dependency graph, and approve the pull request.
It just needs to communicate.
e.g. authenticateUser. createSession. resetPassword.
Ordinary names carrying ordinary meaning.
Another developer can open the code and begin constructing a mental model of what is happening, even if they disagree with some of the decisions. In theory, if AI really made human readability obsolete, that should be more than enough. After all, AI is a computer, and computers understand code.
Except apparently it is not enough.
Another layer of language
Now we need another layer of language surrounding the code.
We need prose explaining the architecture, the conventions, the dependencies, the intended behavior, and the mistakes the agent has already made and is hereby instructed, sometimes in language bordering on a restraining order, not to make again.
We need examples. We need carefully worded instructions. We need files telling the AI how to interpret the other files.
Our own development practices are trying very hard to tell us something. To understand and act effectively, AI coding agents need context. They often need details made explicit that experienced developers already carry around as tacit knowledge.
Which brings me to a rather different conclusion:
The readability of our code just became more important, not less.
The same qualities that help a human reason about a codebase also help an LLM make sense of it. There is no magical dividing line where language that helps human beings reason suddenly becomes an impediment to a language model.
The category error
I think the mistake comes from assuming that because an LLM runs on a computer, it must reason the way a traditional computer executes instructions.
A normal deterministic program executes predefined instructions. An LLM generates responses from learned statistical relationships, conditioned on the context it receives.
Those are very different operations, even if both ultimately happen on silicon.
An LLM would not become a better reasoner if we made it read and write everything in binary. It is not sitting there wishing we would quit bothering it with all these meaningful names so it can finally get down to the ones and zeroes.
Yes, binary is involved underneath it all. So is machine code.
Binary is involved underneath this article too.
That does not mean I would express myself more clearly by writing it in binary. The human brain operates through electrical and chemical signals, but nobody has suggested Mark Twain would have been funnier if he had written in voltage.
Abstraction is not merely a concession to human cognitive limitations.
It is an efficient representation of meaning.
Strip away meaningful structure and you have not liberated AI from the burden of human readability. You have removed information.
The neediest reader
Readable code is not on its way out. Quite the opposite.
We built a machine that was supposed to make readability unnecessary, and then immediately started surrounding it with READMEs, instruction files, examples, conventions, comments, and several small novels explaining what the code means.
Turns out the machine is not above all that.
If anything, it is the neediest reader we have ever had.