Skip to main content

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!


Comments

Popular posts from this blog

Galliventurer - Dreaming of a Universe

n. Galliventurer - one who adventures whilst gallivanting. We have a name. A compound of the words gallivanter & adventurer it fits the game quite nicely. It will also be the name of the player's ship (though, you may be able to have many ships throughout the game). Also trying something a little different for this project, practicing what I preach as it were. I'm actually going to plan this out a little bit before I ever actually write any code. Oddly I feel that most of my hair brain schemes of previous years have had a fast paced "rush to market before someone else thinks of this" attitude. So obviously there was no time to stop and take a moment to put any thought in before code went into editor. None of those projects ever made it out of the proof of concept phase oddly enough, no prizes for working out why. In the spirit of all this, things are different this time around. Having given it even two minutes of thought there are several issues....

How to Think

Moving an arm and thinking about moving an arm are two vastly different things. Even thinking about thinking about moving an arm is a natural thing to do even if reading it is very odd. Now the hard part, how to you design thinking ? The deliberate process of simulating scenarios to either logical or illogical ends would seem like a great fit for computers that can do millions of calculations a second. The slow an deliberate winding down a thought path seems to be the missing link to truely intelligent machines. We are very good at making machines. Even more so machines that actually produce things and have purpose. Since the earliest primitive forms of man, our tools are defined by their use. Or more aptly by the end result they achieve. So what is the end result of smart machines? To drive our cars, build our structures, do the heavy lifting and manage our lives? To do all that the ability to compute and apply action is needed but not actual thought. Most business tools and modern ap...

The Worker Bee

Do what you're told, follow the rules, don't over step your bounds, stay in your lane. The true cornerstone of modern enslavement to work. "We can't all live our dreams", why is that? Because then we'd have to change, to collectively actually think and enact a way all people could realistically achieve a base standard of living & contentment. Allowing people's mind free reign on real questions rather than worrying where the next meal is coming from & keeping the lights on.  Bee animation by  Joe le Sale While I have no answers to life's great mysteries, I do know this about the meaning of life - it definitely isn't to toil & labour day in and day out to fill the wallet of our bosses or investors. So how is it that we find ourselves with that holding such a giant sway over our lives? This of course is rhetorical, we all know the answer, you don't bite the hand that feeds you. Which brings the problem in to sharp focus, we no longer ...