Documenting My Lack of Documentation

This is a public shaming. No quarter will be given, no merciful anonymity or private repo's will suffice to hide my transgressions. I wrote a large complex recursive piece of functionality that was all but absent of documentation!

At the time everything seemed so simple, so straight forward. I thought anyone on my team could open up the code, read a few small lines and instantly understand what was happening, even first thing on a Monday morning before coffee. Or so I thought. 

Now fast forward to me on hump day last week, several months after writing that functionality. "That thing I wrote a few months back, it'll be perfect! Might need one or two miniature tweaks, should be simple", what an idiot. Should be simple - never utter those words! For all that you hold dear will turn to ash. Code that is as tight as the vaults of Fort Knox will turn to spaghetti riddled with bugs, like a scrap of peanut butter & jam sandwich consumed ants at a picnic. So much as whispering this phrase invites doom and destruction upon you and your codebase.

The function itself isn't outlandish or hard to follow, it's the spectrum of scenarios it can be applied to within the microservice that really makes it powerful. It is easy to misjudge how it works and the outcome changes wildly in a few select cases. Couple this with a severe lack of sleep and a devastating lack of documentation, wouldn't you know it, we've arrived at our destination - I was utterly bewildered and confused. It took two days to fully rediscover all the intricacies of how it fit within the microservice that housed it. Not to mention that time it took to make the changes. Needless to say it wasn't one or two tweaks. 

This is a public reminder to myself to always document as I go! "There's never enough time to document", past me can bend ober and shove that where it fits! It would have taken a 20th of the time to write down some sliver of documentation for the process flow. Rather I spending timea wading through debuggers, logs, unit tests & console output to work out what the hell was actually happening to the data! Better yet, document up front! Outline the functionality and perceived solution/implementation from the outset before even touching code, that way it's half done already. Just write some documentation!


Popular Posts