kbrecordzz
Home - About - Contact - Overview
* Company diary *
Video games are made of code (mostly), and code can easily become very complex. And since you need to understand what you're working on, both creatively and technologically, you must understand the code fully. For my last game I solved this by not letting it grow too complex so I could understand the whole code by just looking at it (it also helped that I had recently created almost all of it from scratch and had all the connections and systems fresh in memory...), and also by making the game very linear, meaning there's only one order you can play through the game's events in, which means much less possibility for parts of the code to interact weirdly with each other since everything is separated.
However, for a more sophisticated game like MANAGO (the game is either done or not done, depending on when you read this), I can't rely on understanding the code by simply looking at it. I can't keep the game small, simple and minimal, because I want to create more than that. More than I can keep in my head at one time, more code than can possibly be grasped by a short look of a human eye, or even a couple of long ones. And since the game's events, in a non-linear fashion, can occur in many different orders and affect each other in many different ways, trying to understand what actually happens in the game by looking at separate parts of the code won't really work.
Long story short, to understand a project like MANAGO, I have to resort to documentation...
As I said in the previous post of this series, I want the production capacity of a company but not the administration burden of it. So when starting to put more time on documentation, it's important to not become a company filled with administration and "around-work" that takes all time from the real work. So I have to document as little as possible and get as much out of it as possible. "Real" companies solve their complexity by creating systems to handle it, which in turn also grow so complex that they need to hire people to specifically handle those systems. That's what I don't want, especially not for programming related tasks, since the knowledge of the code as a whole then would be divided among multiple people. I believe that good and efficient code relies on one person knowing how all different parts work together, which is lost when different people are working on different parts.
My principles for documenting enough, but not more than that, are:
Don't document everything. Write more about the important parts, less about the less important parts, and leave out the least important parts.
When writing about something, don't hide details and don't assume the reader (you in the future) will know what you mean. Write briefly and concisely in clear human language, and involve technical concepts from the code when needed. By forcing yourself to write clearly and don't skip over details, you also force yourself to understand your project as a side-effect.
Mark with "IDEA:" when you come up with an idea for something to do, so you can come back to the document and quickly find tasks to do.
Mark with "-- WRITE MORE HERE --", where you're not done writing. So you can come back to the document later, even much later, and continue filling it up with information without wondering what's even left to add.
All this is to make the document easy to come back to and understand even if you forget about it for 6 months. It shouldn't be too long and boring, it shouldn't have the risk of becoming a "dead" document, it shouldn't be underexplained, and it shouldn't assume the reader knows any context or remember what they wrote last time. And besides coming back to read the document in the future, you should also be able come back and work more on the document in the future, and not rely on the sudden burst of inspiration at the start of doing something like this, because that fire will burn out and you still have things to do.
Bonus: Colorize for how much something matters, how much it affects other things, or how much that code is run. How important a part of the code is is hard to grasp from just looking at the code, but a color code for it gives us instant information. Things like how many times a piece of code runs every frame, or how a piece of code relates to other parts of the code, may be hidden "between the lines" or at least require looking at several vastly different parts of the code, which is hard to do in a large codebase. So right now I use color to show important structures you can't see in the code.
And remember that this type of clear documentation depends on the code not suddenly changing after a couple of month. Otherwise the documentation will stop being true, and all the common problems of being a company will start to occur. There's no coincidence that I came up with this system for my second project, where I both reuse old technology from my last game that's stable and proven to work well, and also have a hard time remembering how it worked...
Also, remember to throw away the document as soon as it doesn't help you anymore. Systems and documentation have no purpose in themselves.
This documentation, both the process of writing it and the document itself, can help with finding performance issues, potential bugs, unused or unnecessary code, inconsistent and badly written code, getting a clearer understanding of how the whole game system works, and also for more creative parts like showing what content is actually in the game, what needs to be added, where to put more focus, what thing to create in the game next, how to connect different parts of the story, which characters are used more or less, etc, etc... It's supposed to give you both information about the details and about the whole at the same time in a concise document, compared to the code itself where you either see the whole or a detail at a time and have a hard time seeing nuances and connections.
Advertisement (illegal to click the link)
by 
