Read Code as if it Were Poetry, Write Code as if it Were Prose

In the age of human and AI collaboration, are you building for reading?

Oct 06, 2025

(Image: How to spend an excellent afternoon in New York City — The Morgan Library & Museum)

This entry in the Software Enchiridion follows on from the short story,
“The Compiler and the Poet”

An act of creation in software begins in reading, exploring, questioning. Probing what is there to build an understanding of what might change.

Before you can write well in code you must learn to read what already exists. Most developers think they are building systems for execution. In truth, they are building systems for reading—for the next human (or, these days, AI) who must hold the whole fragile machine in their head and not drop it.

When you read code, your brain does not simply parse instructions. It performs a deep act of translation, turning tokens and syntax into narrative and intent. It is a conversation across time between two minds—one that wrote, and one that reads. Cognitive science shows that when you read someone else’s code, your brain engages in a process astonishingly similar to reading poetry, but with added burden: the need to simulate a running machine while preserving a human story.

First comes the parsing. Your eyes pick out tokens like a reader catching sight of rhythm or rhyme—if, {}, class. The brain stumbles on the unfamiliar the way it might on an archaic word in Milton. Then comes the chunking: patterns form, idioms emerge, loops and handlers take shape. The experienced reader sees these not as lines but as phrases—gestalts of intent. As in chess, experts do not see pieces but positions.

Next, the brain builds a model. It runs a quiet simulation—data flowing through branches and loops, side effects propagating like echoes in a sonnet. This model-building is why good names, short functions, and clear flows matter: they reduce the cost of thought. Every unnecessary abstraction, every clever trick, is a demand on working memory. The mind only holds so much.

Then comes the shifting of scales. You zoom from micro to macro, from the line to the system, the same way a reader toggles between a single word and the theme of the poem. The brain seeks coherence—a story that holds together. That’s why naming, structure, tests and rhythm matter so deeply in code: they are your narrative scaffolding. They tell the reader, this is where you are in the story.

Finally, comprehension becomes reconciliation. You align what the author intended with what you expect. When design and understanding coincide, reading is smooth. When they clash, the friction is felt as fatigue. In that moment, reading becomes debugging—an act of repair.

And here lies the art. Code and poetry are both languages that summon worlds inside the mind. Poetry invites ambiguity, so that each reader’s world is unique. Code forbids ambiguity, so that every reader’s world is identical. Yet both demand craftsmanship in hospitality—a respect for the human who will enter the text after you. In both, your job is to guide, not confuse.

Richard P. Gabriel once asked if code was habitable—if one could live inside it. That is the truest test of any platform, library, or service you build. Does it feel like a home or a trap? Do its corridors make sense? Are there windows of documentation where light gets in, or only mazes of indirection and shadow?

When you build platforms, you build reading experiences. Every API, every workflow, every error message is prose and poetry. You are writing a story about how to move safely and meaningfully through complexity. If you make that story clear, others will read it, extend it, and build upon it. If you make it obscure, they will abandon it.

The best developers read code as if it were poetry—attentive to rhythm, form, and hidden intent—and write code as if it were prose—plain, honest, and true. They understand that the future of every system depends not just on how it runs, but on how it reads.

So ask yourself, with every commit, every interface, every abstraction:

Are you building for execution, or for reading?

Because reading is where all understanding begins—and where all good software, like all good writing, endures.

Maxim

Code and poetry are both spells: one cast for the machine, the other for the human. When you read code, your brain works like a poet’s—seeking rhythm, structure, and hidden intent. When you write code, you must resist the poet’s temptation to multiply meanings. Code should be prose: plain, direct, and alive with clarity.

Reading someone else’s code activates the same machinery of thought as reading poetry:

Parsing symbols like a metrical line.
Chunking patterns as sonnets or idioms.
Simulating meaning—in poetry, imagery; in code, execution.

But there is one vital divergence:

Poetry thrives on ambiguity, layering meaning.
Code attempts to collapse ambiguity, permitting only one meaning.

The mistake of the poet-programmer is to delight in cleverness where clarity is required. The mistake of the dull-programmer is to strip away rhythm, voice, and narrative, leaving only syntax for machines and no guidance for humans.

Good code lives between: poetic in its hospitality, prosaic in its intent.

Some Practices

Name with narrative: Functions and variables should read like a story the reader can follow without translation.
Balance density: Avoid sprawling prose or cryptic haiku.
Comment as chorus: Comments are not the main act, but they can give the reader the rhythm of the scene.

Some things to avoid

Writing code as riddle or puzzle.
Valuing cleverness over clarity.
Assuming readability for yourself means readability for others.
Removing all humanity in pursuit of machine-perfect minimalism.

A helpful checklist

Could someone unfamiliar to the codebase read this and follow the story?
Are names single, unambiguous metaphors?
Does formatting reinforce meaning rather than obscure it?

Code and poetry use the same cognitive machinery, but the aim of code is clarity where poetry seeks ambiguity.

Write code with the rhythm of a poet but the intent of a novelist—hospitable to humans, unambiguous to machines.

A Software Enchiridion

Discussion about this post

Ready for more?