Why it is hard to write about code

As a programmer and occasional author of programming topics, I find that writing about code is one of the most difficult exercises in writing. Here are a few reasons why.

Writing about a thought process is really hard

I often find it completely futile to replay how I decided to write some piece of code — with all the strange knots I got myself into and out of at the time I was coding it. I remember little fragments of how I felt during particular moments of pain, frustration, and triumph, but the details of these fragments are quite difficult to sew together into a cohesive story for another programmer to really understand.

After all, most of the time I spend writing code is actually spent re-shaping it. I write some code, move it around, consolidate, refine, redo, and occasionally overhaul it. My palette lives in bits and pieces on screen, and bits and pieces in thought. That just doesn’t make for coherent storytelling.

Why did that extra variable seem essential then, only to be thrown out later on? How come I coupled two concepts that, clearly, shouldn’t have been coupled? And, why did it take me a week to realize these now-obvious missteps? It’s often hard to detail these answers in written word, after the fact.

I think that is why, in our industry, we usually write about things (like pattern, constructs, and tools), not thought process; we write about the end result rather than the often-circuitous voyages we experience in the midst of programming. But, it’s in those strange voyages that we actually learn the most. They’re just hard to capture accurately on paper.

Palatable examples to write about are often too simplistic

When I write about code, I tend to stick to straightforward examples — much lighter fare than I deal with in the real world with more well-worn paths. Maybe it’s a few database tables, a simple ORM, a conveniently straightforward domain layer that seamlessly maps to a front-end application. When I show example code, the path from point A to point B is usually pretty clear. If someone learned all about programming just by reading my posts, they’d probably be wondering whether I can build anything else besides blogs and shopping carts.

But, my intention is to have the reader extrapolate my comparatively trivial example — how a small misstep on a relatively simple problem might lead to a huge, tragic fall on a much more intricate one. Maybe, one day, when a reader ultimately finds himself somewhere on his hands and knees along the side of a dark and lonely road, he’ll remember some little snippet of an idea I wrote about once that will eventually lead him back to the well-paved road lined with fluorescent lights.

Analogies aren’t always true to form

Programming is an extremely visual art without much in the way of actual visuals to describe. So, when I do write about code, particularly the pains of difficult code, I usually lean my entire body weight on analogy. In my usual arsenal of descriptors are metaphorical leans on mechanical engineering, architecture, cooking, and, well, writing. They each have far more obvious visual references, and you can get a fairly good sense of a software problem by cherry-picking a good analogy from one of these other disciplines.

But, let’s be clear. No single analogy is entirely correct. For instance, some may say that programming falls along the same lines as traditional engineering — you know, making steam engines, airplanes, or buildings. And, in many respects, it has; common titles in the industry include architects (who do more high-level “blueprinting” of how an application ought to be built) and developers (who, to an extent, follow the vision of the architect). Historically, we’ve ported a lot of the methodologies that drive traditional engineering into software development.

But, over the past few decades — and particularly since the rise of the Internet — these two disciplines have begun to diverge. The medium that software lives on, and the tools that the community has developed and shared through movements like open-source, have antiquated some of those ported methodologies of yesteryear.

The other obvious difference between traditional architecture and software development is the lack of physical constraints. Buildings must be constructed in a particular order. The architect who insists on constructing the walls of a room before putting the plumbing inside the walls will soon be looking for new work. And, perhaps, that new work might fall somewhere inside the programming industry.

We can talk about coding as a kind of construction. We build modules and interfaces that house various functions. Coders build these components in isolation before fastening them together to make bigger components. There are dependencies — the code in one room might need to “talk” to the code in another room. But, in development, there is no necessary order that has to take place. You can shimmy a pipe between two walls even after the last brick’s been laid, without much effort.

But, the effort isn’t futile

So, with all that makes writing about code really difficult, is it still worth the effort? Absolutely. As readers, we just need to understand how to use the knowledge we gain from reading about code. The attempts to write about something so difficult to describe in words are meant for you, the reader, to take and squeeze whatever ideas you can out of it, and apply them in the far more gnarly situations that actually happen in the real world.