On Building Software
Why it is Hard to Write About Code
George Carlin once said that nothing is so boring as listening to someone describe a dream. This too is true of your futile attempt to replay how you decided to write some piece of code — with all the strange knots you got yourself into and out of at the time you were writing it.
You remember the loose fragments of how you felt during particular moments of pain and ecstasy but the fragments are too difficult to sew together into a cohesive whole for an outsider to really understand.
Most of the time spent writing code is spent stumbling through it. Embarrassing, amateurish problems in retrospect. Sometimes you spend just as much time unwinding the mess, hunting for the breadcrumbs to get you back to just before you started down the wrong fork in the road.
This doesn’t make for good storytelling. Too dreamlike.
You may have accidentally wrapped yourself inside your own silk web of objects nested inside of other objects now better off unwound. An extra variable essential at one point thrown out later on. Two concepts once coupled, now split, a revelation made, later recoupled in a different way.
It’s very hard to detail these moments in a way that feels authentic and so we go for the cheap route — the final revelation.
We almost always write about things like patterns and constructs and tools, the end result rather than the circuitous voyage we take during the midst of programming.
We don’t write about our most difficult coding experiences because they are too difficult, painful, and tedious to describe. If you weren’t there with us in the moment, you might not see why we chose the then-sensible-but-now-ridiculous path we did, or fully understand the multitude of worries we juggled ephemerally in our minds at the time.
Experienced coders know this. Talk to a fellow programmer who is in the process of going down one of these murky paths and you will feel the anxiety. A solemn nod and a pat on the shoulder will do. The good ones always find a way to pull through.
When we write about code, we tend to stick to straightforward examples — much lighter fare with well-worn paths. Maybe it’s a few database tables, a simple ORM, a conveniently mapped domain layer that seamlessly maps to a front-end application. When we show example code, the path from point A to point B is usually quite clear.
As programmer-authors, we hope that the reader extrapolates our comparatively trivial examples. When the 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 he read once that will lead him back to that well-paved road lined with freshly painted arrows.
So, is writing about code writing worth the effort? Absolutely. As readers, we just need to understand how to use the knowledge we gain from reading about code — that a writer’s attempt to write about something so difficult to describe in words are meant for you to take and squeeze whatever you can out of it, in the far more gnarly situations that you’ll surely encounter.
