On Writing Informative Programming Texts

Reading Time: 5 minutes

A pattern of purple, orange, yellow, and green

I recently picked up Crafting Interpreters. It’s a project in progress from ex-game designer and current Dart language developer Bob Nystrom.

I found Crafting Interpreters by accident.

See, I write mobile apps. I live stream some of my development work for one of them. Folks regularly ask me about Flutter, the dual-platform framework out of Google and written with Dart. I found Bob (and Crafting Interpreters) while reading about Dart.

Here’s a secret: compilers and interpreters have remained largely a mystery to me. I signed up for Dave Beazley’s SICP course at the end of the month, and I’m nervous. I thought Crafting Interpreters might give me the jolt I need to walk in with confidence. If SICP were an endurance event, Bob is my parasocial personal trainer.

I don’t know whether I’d call Crafting Interpreters a book, but one thing became clear the moment I started reading: Bob can write. He does three things particularly well—things that are rare to find in informative programming texts.

First, Bob explains critical details that other texts gloss over.

In the first chapter, he mentions that a language can compile itself. Most texts stop there. Bob instead includes the dirty secret: that you can do that, but you need a compiler written in another language first, which you use to compile your language once, which you then use to write a self-hosted compiler. Turns out I’m not a computationally stunted dweeb; rather, a critical detail had escaped all the other explanations I had read.

I don’t know whether Bob managed to correctly guess which details needed to be included. If you’re writing a programming text and you’re unsure whether you could make these guesses, you have another option: find a set of frank editors who possess the confidence to admit what they don’t understand, and ask them to rip your drafts to shreds until they can’t anymore.

Second, Bob understands meter.

Your high school English teacher may have mentioned iambic pentameter—a pattern of ten syllables, the even ones stressed, the odd ones unstressed. Many of Shakespeare’s sonnets use this meter. Though informative writing doesn’t hold a strict pattern like that, meter still matters. Check out this piece by Eden Robins, or this piece by Eve Ewing. They distribute stress and rest in their writing to give it a rhythm that translates to the voice narrating their work in your head. That rhythm makes the pieces easier to read and absorb. Bob achieves this, too. The voice that narrates Crafting Interpreters in my head sounds like it’s telling me stories over afternoon coffee. I learn easily this way.

Perhaps meter comes naturally to you, the potential author of a programming text. But if it doesn’t, I have good news: you can learn. You can start by finding and reading essays like the ones linked above. I find that my meter in the pieces I write frequently mimics, to some degree, whatever I’ve been reading lately. You can take advantage of this effect, too.

Third, Bob shares stories about the people connected to the technology.

Computer science is peculiar; unlike natural sciences, it is one hundred percent human-made. This means that individual thoughts and personalities govern the way everything works in our field. We downplay this, I suppose, in an effort to make computer science seem more rigorous. But I think that is a mistake. We are, by nature, social creatures. Our brains evolved to collect, store, and reason about the individuality of others. We devote whole parts of our brains entirely to human facial perception. How valuable it is, then, to index vast and complex troves of information on something our brains developed precisely to remember—people.

In the second chapter of Crafting Interpreters, Bob shares the story of Gary Kildall, who wrote the first transcompiler. I won’t spoil it for you, but the dude lived a life. I’ll be interested to see, as I continue through the project, if the stories shared are all of white dudes; that’s an easy trap to fall into, as we frequently erase women and people of color from computing history. I’ll update later on my findings.

I’ll post updates on the blog as I work my way through Crafting Interpreters.

In the next post of the series, I’ll share some of what I’m learning from exploring the compilers for Swift, and possibly Rust as well. First, though, I wanted to seize the opportunity to dissect what makes Crafting Interpreters such an appealing introduction to its subject.

It’s common to assume that writing (and artistic pursuits in general) are purely a talent. There are techniques to them, and techniques can be taught. Crafting Interpreters exemplifies three techniques that especially bolster the effectiveness of an informative programming text. My hope is that, if you are looking to write a programming text, these three techniques give you some starting points to turn your knowledge into the inspirational and informative tool of your dreams.

If you liked this piece, you might also like:

This recent live stream about the abstraction gradient (featuring a koala gif)

This talk on giving and receiving feedback (another helpful skillset for maximizing your impact as a technologist)

This three-part series on building an efficient in-memory database (no big O notation involved)

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.