Read Me

When I'm finishing up a big chunk of work I greatly enjoy investing time in writing a good Read Me. It's a bit like a travelogue of a 18th century explorer, but instead of failing to find the Northwest Passage, I'm merely trying to close a Jira ticket -- "O look how far I've come, and I have no real idea where I am, and is it not glorious?" my Read Me proclaims, except not from quill and ink but from the obnoxious clip-clop of my mechanical keyboard.

“For I know not why my gums are the dark purplish green of angry algae, nor why that database function fails only sometimes, but I am certain truth will be evident to all when I am home and committed to the repo, and her majesty the Queen." Then, submitting my pull request, I become the triumphant Captain walking down the gangplank after years at sea, squinting at the board to survey the remains of the seasons and sprints I left behind, and <recordscratch>, oh dagnabbit, there's a typo and missing punctuation, I'm going to have to push to this branch again. I would bet the same thing never happened to James Cook while writing his journals, especially if he had a good linter.

A good Read Me can be full of education and entertainment for other developers, as well as my most important reader: Future Me. Have you met Future Me? I haven't either, actually, but I imagine Future Me is very much like Present Me, and like Past Me for that matter, except he's probably got less hair, and a heightened awareness of the larger operational and business context for this code I'm about to commit. But Future Me surely lacks the detailed familiarity that I have in this “fresh back from the sea, with the taste of salt on my lips” moment of confidence and mastery I'm in with my code right now. My Read Me does it's best to pull Future Me back in to the present, to feel the considerations and compromises, so that I may one day be able to efficiently travel upon this ship again.

And while Present Me is confident in my code’s ability to conquer all the requirements, I know that Future Me has a superpower: hindsight. Like the winds below the Tropic of Capricorn once foretold by stars and sextant, so too will future product requirements change, but by the compass needle of alerts and backlog bugs. While Present Me can only guess at the future desires of our beloved customers, my Read Me will capture all the optimistic ways that my code will be robust and scalable, my design resilient and yet easy to change, when Future Me is tasked by Future Courtney (she's our master navigator, aka leading our Product Management) to perform inevitable enhancements. And as I commence work on the new requirements, juvenile Present Me will possibly seem so very, very myopic, but his Read Me serves as the compass rose, the clue to begin again.

After all, in a team context, and in virtually any professional context, there's really one primary goal whenever one pushes off into the sea of "I'm going to write new code to fulfill these requirements", and that's maintainability. Oh sure, there’s a non-zero chance we never ever have to crack this code open again, either because it is totally freakin’ perfect (possible but unlikely), or it never gets any use at all and is quickly forgotten (it happens...it happens to all of us).

At the core of maintainability is the classic problem of complexity, specifically, having too much of it. In his book “A Philosophy of Software Design” John Ousterhout writes:

"Complexity is anything related to the structure of a software system that makes it hard to understand and modify the system."

Successful software systems, the ones that do meaningful things in the world over a meaningful period of time (versus, say, homework assignments and freelance deadline work you never see again after the check clears) eventually all need to be modified. And to be modified they need to be understood. The complexity that makes this difficult, says Ousterhout, is often caused by obscurity.

Obscurity takes root in many forms: it's bad code design, it's bad variable names, it's non-obvious dependencies. It's a very compact bit of code that wraps four lines down into one, but renders the code to be four times less readable. It's design patterns wrapped in design patterns, which all feel impressive and so very textbook, as if writing more and more code were an athletic competition in front of imaginary judges.

Complex and obscure, in any sphere, is often viewed as intimidating, daunting, and more valuable -- but really any developer can refactor a prototype as innocent as a Forrest Gump limerick into a thicket of code that reads like Finnegan's Wake, chasing the imprimatur of the academic textbook or message board neckbeards. The curve of readable code bends away from "oh I get it" towards "oh my god" in such an organic way, that it feels as natural as the sky is blue. Indeed, Joel Spolsky called this a fundamental law of programming: it's harder to read code than to write it.

And while some of the obscurity of software is due to the complex interactions of distributed systems, symbolic representation, and the magical transition of ideas into electricity, the true source of complexity is the same as it ever was: people. Or in this case specifically, a person: Present Me.

Just as there was no easy answer for a Northwest Passage in 1776, no Read Me is a panacea. It took a few more centuries, an industrial revolution pumping a whole bunch of carbon, and climate change to break that ice – certainly an unfortunate outcome in this era of container ships. For you, Future Me, there is no simple solution to the natural entropy created in software development, except this meager offering, which can be shelved into the library of journals in the archived repo graveyard, with a sidelong glance to Lehman's law of software evolution: When a program is modified, its complexity will increase and quality decrease, unless it is rigorously maintained and adapted.

The distance from no documentation to not enough documentation is very, very slight, but the distance from some documentation to enough documentation is very, very long. Writing long love letters to Future Me feels self indulgent, but leaving behind a map of the journey to now for the future to find is invaluable.

As I like to remind Present Me - "You’ll thank you later, you always do."