Technical Dev Blog #5: Documentation, Documentation, Documentation!

By @ 08/16/12 in techblog

For a bit of context, before developing our game, I developed (and still develop, at least until we magically stumble onto this mythical ‘income’ and ‘success’ stuff I keep hearing about at the IGDA Sydney events) helpdesk and financial systems, mostly database-driven web apps.

After years learning my trade at a tech-shop, I began to work on my own, and for the past few years have built helpdesk systems internally for a mob with the money to do so. Thing is, that while I had it beaten into me savagely that documentation and in-line comments were the most important things about what we did at the tech-shop (proven every time someone failed and profanity-laced verbiage took to the air come deadline-time) years of working as the sole programmer in the wild west that is my current place of employment… I began to worry that I was getting lax.

It’s easy enough to do – when you have no other coder watching over your shoulder or having to either interact / build upon your code or die trying, the number of comments in your code become fewer and the quality of your technical documentation can become, well… sub-optimal.

This became a big concern for me when I suddenly found myself not only working along-side another programmer, doing the more complicated stuff, but also because I’d be implementing game data structures which would then need to be completed by Leigh, who would be putting the details into our game engine to implement the 200+ objects, recipes, and spawners which make up our gameplay (Think of the luddites! – Leigh).

Sure, it’s obvious to me that an object has multiple looks and within that, multiple states and within -that-, clear and simple values such as “WhenTappedTurnInto” or “Harvestable” or “Grows”… but not only might it not be clear to Leigh or whoever else was blearily turning our design document into actual numbers and links – it might also change.

Indeed, it would almost certainly change, and when it did, it was more vital than ever that I document all these little changes. For instance, when ‘Grows’ and ‘Harvestable’ became distinct and unique, Leigh needed to know this, and telling him via an email he might read late at night or forget due to a lovely glass of Riesling or seven, I needed to be sure that every value, every part of the structure, was clearly laid out for him at all times.

This was stuff I knew, and I’m sure it’s stuff which is currently in the process of boring you to tears (assuming you’re not endlessly fascinated by the poetry of the way your web browser renders blocks of text, or something).

What surprised me, after a few months of development, was that my two big reasons for documenting and commenting my code better than ever before (which, to sum up the last few hundred words in one sentence was: multiple programmers and designers having to access the code) were not the reason I found my documentation useful (I was just playing the long game. Knew what I was doing the WHOLE time. – Leigh).

The first reason was this: optimisation.

In game development, especially on devices with less than ideal amounts of memory or CPU time available to you (like, say… mobile devices) you find yourself constantly going, “Okay, this is too slow. How can I make this faster?” or “How can I make this use little enough memory to work on the Nokia 8500 with this slow-as-change-in-the-conservative-party CPU and barely 2K of memory to smack together?”

When you’re trying to figure out how to make something faster, the most important tool you can give yourself is -your own thoughts-. Why did I choose to iterate over the entire of the sum of these two rectangles instead of simply working off the non-overlapping areas of them?
My own comments, explaining why I made that choice (for instance: a technical limitation, “I thought it’d be faster” or even “so game technical requirement [X] doesn’t break this”) have been enormously powerful tools.

Can I speed up this routine by changing the way it does [X]? Well, I’d better read through my comments and find out if there’s something I’m missing. Perhaps that odd choice to iterate backwards through an array was actually a really important choice, and not just the result of a fevered 14-hour coding session where I’d forgotten my name or how to properly fire a stinger missile in Battlefield 3.

The comments may be useful for my fellow programmer, but they’re thrice as useful for me. Having a map of your methodology is the best way to improve your technique.

And the second reason? Sanity-checking our own game mechanics.

Every time I add a new feature and add it to our technical development documentation, the designer reads it – he has to, as he’s the one using it. He’s also the one changing our ideas and gameplay concepts into hard numbers, and that being the case, comparing the technical specifications document and the technical development documentation means he’s more likely than ever before to say, “Hey, you know how only objects that are impassable can be harvested by NPCs? Well, I think that conflicts with our idea of implementing auto-harvesting for turnip plantations.” (Think of the turnips! – Leigh)

Or even, to ask, “Hey, based on your documentation we could easily make trees in forests do [insert name of thing here]? We didn’t think of that when we wrote the design doc – would it be worth adding it?”

In short, documentation IS useful. It’s the most useful thing you can do – but in our case, not for the reasons we thought.


Comments are closed.