Is well-written code more like poetry or prose?
As I've deepened and expanded my engineering skills, I've picked up a few helpful practices and perspectives, and I'd like to share one in particular that has been especially useful.
Before I share it, though, here's an old joke about the progression from junior to mid-level to senior developer:
Junior dev: My code is simple, straightforward, and easy to understand.
Mid-level dev: My code is clever, innovative, expressive, hyper-optimized, and ingenious.
Senior dev: My code is simple, straightforward, and easy to understand.
(I've come across multiple versions of this joke, but the one I've paraphrased above comes from John Arundel.)
I love jokes like this one, because the punchline works on two levels. On the surface, it's a dig at the hubris of mid-level engineers. But on a deeper level, there is humor in the seeming lack of contrast between junior and senior devs — even though developers themselves know that there is, often enough, a large gulf between them.
The joke also serves as a good lead-in to the perspective that has helped me write better code.
In software development, "clever" solutions are like poems:
My poem about poetic code
Beautiful, evocative, crisp
With dense meaning packed into each phrase, each line
Written with care by an artisan who bends language to their will
Just as a poet feels
when they've wrung their heart onto the page
So the author of poetic code feels
about their
novel_caching_function
To mid-level engineers, writing this sort of poetic code has an intoxicating appeal. It allows them to flaunt their talents, demonstrate their mastery of the language, and impress their colleagues with their ingenuity.
But more often than not, what is really needed is the code version of ordinary prose: straightforward, with a preference for clarity over succinctness, easy for others to understand, easy to edit, and with fewer surprises and deviations from convention than a poem.
The problem with poetry
Think about your favorite poem. If you don't have a favorite, here's one to consider.
Imagine if that poem were causing an issue in production, and you needed to completely, thoroughly understand its meaning to be able to diagnose the problem. Then you needed to somehow excise an errant word or line to vanquish the bug.
In the best poems, there are usually multiple layers of meaning, nuances and subtleties, some harder to tease out than others. Sometimes you have to sit with a poem for a while before you are able to truly drink it all in.
Ideally, not a single word should be unnecessary or out of place. Just as a small tweak to an input string will drastically change a hashing algorithm's output, so too can a small change to a poem introduce fundamental changes to its interpretation.
On the other hand, with prose, particular the sort of no-nonsense style found in wire news reports and explanatory journalism, the best work is easy for the reader to comprehend and lends itself to being edited. For instance, a skilled copy editor can condense it to fit, if need be.
True, not all poetry conforms to this description. Neither does all prose. There is prosaic poetry and poetic prose. There are verses that are still messy and subject to change, and there is prose that is fragile and hard to edit. The line between prose and poetry can be, as the above-linked poem touches upon, indistict to say the least. Nevertheless, if we agree to set aside the outliers, there are certainly discernable differences between typical poetry and typical prose that are useful for the analogy about writing code.
Impress future maintainers
If you are collaborating with other developers on a project, or if you think that at some later point another developer might inherit and need to maintain any of the code you have written, then poetic code, while it might get the job done, can be a liability.
To produce well-written code, your goal should not be to impress your code reviewer with your cleverness — but to impress the person who needs to maintain your code three years from now. The place for poetry, by and large, is not in production code but in hobby code-golf competitions.
After all, there is a reason why instruction manuals tend not to be written in iambic pentameter. If I want to figure out how to turn on my TV with my newly purchased remote, I greatly prefer a manual that's easy to follow than one written by a budding Longfellow or Dickinson.
Justice Stephen Breyer, writing for the majority in the Supreme Court's 2021 case Google v. Oracle, points out, "Computer programs differ to some extent from many other copyrightable works because computer programs always serve a functional purpose."
We often think of the programs we write as being instructions for computers to interpret and execute.
But code isn't just read by computers. It is read by other developers. And "clever" code rarely seems so clever when those other developers are trying to debug a production issue.
Good prose is not debased poetry
One possible objection to this principle is that it encourages developers to dumb down their code or constrain themselves to only the most well-known subset of language features. Why should a person who's worked so hard to hone their craft need to hobble themselves just so mediocre developers can understand it?
I would answer that just as prose can take many forms — from the crude and perfunctory to the sophisticated and sublime — so too can code.
If, for a complex algorithm, "as simple as possible" is still pretty complex, then no one asks that you do the impossible.
But even in that case, heavily documenting the code is a courtesy to anyone who may need to work with it later — and sometimes that person is yourself.
