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

Random Generation That's Not So Random

While I do want the Galliventurer universe to be procedurally & randomly generated, I don't want it to be truly random. There needs to be a modicum of probability involved. Some weighting so that some things are rarer than others. After all we can have too many diamond covered planets or uranium based suns - as you can see I haven't actually started thinking too much about the composition of the planets, stars, etc. Keeping this probability based random selection in mind, I'm going to be using a dynamically weighted series of arrays to randomly select properties for entities in the Galliventurer universe. Using something very similar to (or based on) this article by Michael Czechowski https://observablehq.com/@nextlevelshit/rejection-sampling-in-javascript . The main bit of complexity here will be the values of a randomly selected property will affect the weights of the next selection. For example the size of a star will greatly change the weight of the probabi

Where's the Fun?

When Galliventurer was first conceived in the bowels of my brain it was during a particularly good session of playing No Man's Sky. I had just traversed several different planets finding old ruins and exploring as I went. The exhilaration I felt zipping around in space and then landing to explore - it was this feeling and the want to continue that on my phone, which persisted for days & weeks, was the main reason I even considered starting development on Galliventurer. No Man's Sky is possibly one of the most ambitious, fully realised games in history - yes it took them a while to get there, but I don't see Star Citizen releasing anytime soon - so it goes without saying Galliventurer will not be anywhere near that ambitious. A small glimmer of space flight amongst the stars with endless exploration. But then what? Subin Kim's freighter concept This has been a constant thorn in my frontal lobe since my first flight through the current build of the game. Sure you ca

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.