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

Vacuous Social Data Sharing

It's the not so secret, dirty secret of our modern lives. We live in a golden age of free services that make our lives interconnected on levels that our ancestors couldn't even fathom. Instantaneous realtime interactive updates and vision of someone on the other side of the planet. For free!! We really do live the utopian lifestyle, or do we? We are being monetized. The really insidious thing is, we like it. We crave it. Likes, follows, subscribers, retweets, pins, shares, the list goes on. We're subsumed in a culture of instant gratification and constant engagement. These "free services" have hijacked the way we think and live, all while making copious amounts of money from the personal data we all but throw at them. Whilst there is an innate understanding in all of us about the nature of how insidious and conniving these services are. We still gobble up every morsel of social media's bright lights and flashy features, mostly without a single thought of wh...

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...

My Shout - App Idea

With everyone working from home a lot more these days, especially in the face of a global pandemic with self isolation in effect in most place still, it becomes tricky to make good on that old "buy you a coffee" promise to your friends &/or coworkers. My Shout is the idea for a service to send things to people by alias only. The service would leverage home delivery services such as Menu Log, Favour, etc. but aimed at sending things to other people rather than ordering for yourself, though that would be an obvious function of the service. The address and location details of the person are only known to the service and hidden from others, it would be a breeze to then be able to gift things to your friends, coworkers, or even favourite creator, etc. that is halfway across the country or even the world without knowing their address. Once a "gift" has been sent the recipient gets a notification and can schedule when to get the gift, or even exchange to an equal valu...

Inkie Beard

Search This Blog