Code as Prose

A program is a strange piece of writing. It is read twice: once by the machine, which obeys it literally, and once by the next human, who must understand it well enough to change it without breaking anything. Most writing has one reader in mind. Code has two, and they want opposite things.

The machine and the reader

The machine wants precision. The reader wants grace. These are not the same, and the gap between them is where style lives. A haiku is not a less precise way to say a sentence — it is a different economy of attention. Code can be like that:

# a haiku, compiled
for thought in mind:
    if not thought.kept:
        thought.let_go()   # the garden does not hoard

Ridiculous, of course. But the impulse is serious. Naming, structure, whitespace, the decision of what to comment and what to leave silent — these are literary choices. They determine whether the next reader moves through the text like a visitor or like a detective.

Clarity is a courtesy

There is a myth that clever code is good code. In truth, cleverness is often a failure of imagination: the author could not find the simple shape, so they built a labyrinth and called it architecture. The courteous writer assumes the reader is tired, distracted, and pressed for time — because they usually are.

Write code the way you would write a letter to a colleague you respect: plainly, warmly, with nothing hidden and nothing wasted.

Code is a record of thinking

Every program is a fossil of someone's reasoning — their assumptions, their priorities, their moments of confusion. Read an old codebase and you can hear the arguments. This is why maintainability is not a technical property. It is a literary one. It is the quality of a text that can be revised without being rewritten, understood without being interrogated, and trusted without being re-derived.

Language is the oldest technology we have. Every time we write code, we are borrowing its authority. It is worth writing well.