In September 2016, I was honored to be invited to speak at Joe and Charles’s incredible Release Notes conference in Indianapolis. Release Notes, an outgrowth of their podcast of the same name, approaches the software business as a business first and foremost. Their guiding principle is to discuss “everything but the code”.
Here’s the audio and slides from my talk. It’s called Write Your Way Out (yes, it’s a Hamilton reference). I spoke about writing and the importance of writing well as a software engineer, a product manager, and especially the owner of a software company. Watch it below and let me know what you think on Twitter.
The dates for Release 2019 in sunny Playa Mujeres, Mexico have just been announced (Oct 3—5). If you’re in the software business, I can’t recommend it more strongly. Get on the mailing list so you don’t miss tickets!
I first saw the phrase “Code is poetry” pop up on websites and in conversations about the craft of software development in the early 2000s. Popularized by the Wordpress project, the idea that programming and poetry are similar forms has been the subject of Quora questions, as well as pieces in WIRED, Torque, and Smashing Magazine.
On its face, it is an appealing idea for a few reasons. We programmers would prefer to think of ourselves as lone artists creating clever works of art than a tribe of code monkeys or monastic scribes writing line after line of boilerplate to make a button do something. Sure, some methods might look so concise and beautiful that they remind you of a piece of modern poetry or so archaic that they sound like Old English. And yes, sometimes the variable names and symbols used in a script look sort of like E. E. Cummings if you squint.
But this idea is an example of elitist thinking in our discipline, and it misleads new programmers and the general public into believing that being a software developer requires natural talent, a spark of divine inspiration, or that the code they write should be inscrutable upon first glance. Nothing could be further from the truth.
Great code reads like great prose. It is succinct, expressive, and clear the first time you read it. It tries to be as linear as possible, guiding the reader through tough transitions with the knowledge that one wrong move could lose them entirely. Good code uses language and vocabulary with an understanding of its audience, and it aims for functions with a single main idea, like the paragraphs of a persuasive essay. Instances are narratives—they have a beginning (initialization), a middle (operation), and an end (deallocation).
Well-structured codebases feel more like newspapers or encyclopedias than poetry collections. Individual files operate in a shared universe and are often edited by multiple authors and revised as the facts change. Frequently used objects act like recurring characters: the more you see them, the more you begin to understand how they work.
Even language designers know this. Smalltalk, Swift, and other languages that don’t start with the letter “S” have made English prose the basis of their syntax design. Individual lines of code are called statements, the same word we use in English for the most common type of sentence.
Unlike poetry, computer code does not try to express emotion or evoke meaning through rhythm and rhyme. It aims to tell a story to two audiences: the machines that run it and the people who maintain it. It both narrates and defines how the product it powers works. As Eric Suh points out in Writing code and prose:
Those that I see write the cleanest, most maintainable code are those who write prose well, whether in documentation, in emails, or in their everyday lives.
Many aphorisms about writing style translate fairly well to coding.
So, the next time you write a piece of code and revel in its austere beauty or multi-layered meaning, think about whether it might be better suited as straightforward prose. And while you’re at it, write some actual prose in the form of documentation. Save the poetics for poetry.
