Gamasutra: The Art & Business of Making Gamesspacer
arrowPress Releases
October 24, 2014
PR Newswire
View All
View All     Submit Event

If you enjoy reading this site, you might also want to check out these UBM Tech sites:

What documentation?
by Timo Heinapurola on 07/31/13 08:23:00 am   Expert Blogs   Featured Blogs

The following blog post, unless otherwise noted, was written by a member of Gamasutra’s community.
The thoughts and opinions expressed are those of the writer and not Gamasutra or its parent company.


This was originally posted in

Imagine a situation where you have just been employed by a game development company with a large code base. You might setup your computer, adjust your chair, get some coffee and then start synchronizing your source code repositories. This might take a long while so you decide to take a look at the company documentation while you're downloading. So you roll up your sleeves and start digging. You dig and you dig, but you just can't seem to find anything useful. Puzzled you go to ask either the CTO or the technical director whether they would have some information as to where the documentation is lurking. So you enter the room of either person and candidly ask your question, only to be met with a blunt answer stating that there is none.

You return to your desk, shoulders slumped, and sip some of that now cold coffee. You decide to wait for the source code update to finish. It now seems that you have to rely on code commenting to figure out how the system works.

Finally the update finishes and you start digging the source code. To your amazement and horror you notice that not only is there no separate documentation on the system but there's also no documentation to be found in the code either!

Let us push that nightmare aside for a while and discuss what is going on in here. The situation is common not only in game development but in other kind of software development as well. It comes down to company culture in many cases. The companies I have worked for expect you to develop quality features sometimes in a tight schedule. Leaders are often focused on implementing features themselves and don't necessarily oversee things such as code quality. Those are implicitly expected of all skilled developers.

In addition to code quality we have the issue of documentation. A lot of my colleagues of past and present might shift uneasily at their desks now. Let's face it, most developers do not like writing documentation. Even Scrum has built into it the idea of only producing the minimal amount of documentation possible. While this does mean minimal in that it should still serve its purpose, it's easily taken as a reason not to write documentation at all. You have code changing all the time anyway, so why should you write documentation that will be outdated the next day?

Why should we document?

The story I told is not uncommon by any means. It's been a relatively constant topic of discussion for the whole of my working life, in fact. Why I think it's so important is that you have people coming in and going out over the lifespan of a company. You could say it's the people that make up the company but it's code that is left behind by those people that forges the future of the company. This is because you can't do a rewrite of the whole product every time you have people leaving or joining the company. So the company is stuck with what the person did before leaving.

Every time you write a single line of code you do it with a plan inside your head. You have an idea of what constructs are required and how they relate to one another. You basically form a whole imaginary world inside your head. This world is then projected into text using the programming language grammar.

Such descriptions using a programming language often becomes quite complicated. This is why you should use methods and well named variables to break down the individual expressions and constructs into understandable bits. For instance, you could write the whole simulation code of a car as a single block but it would make more sense to split it into smaller methods, each of which define a single step in the algorithm.

Such well structured code that is split into sensible bite sized portions that are labeled in a coherent manner can be called clean code. I like to think of you having to understand the main points of what the code does on the first read through.

However, clean code is not always enough. If you were making modifications to the code then clean code will help you considerably, but often you are just using the code in some way. This is especially evident when using a 3rd party library that has a specific set of entry points and data structures. You might not even have the code for it. You have no practical way of finding out what the system does without having samples on every single possible thing you can do with it or having comprehensive documentation.

The same goes for internal technology that is used in a 3rd party like manner. This is the case when using an internal engine, for instance. Documentation allows for people without deep knowledge of the engine internals to just dive in and start using it. Without documentation you could hope someone else already has an answer to your question or you could just start trying things out. I have also noticed that often the methods and classes really can be used in the way that feels intuitive, but you're never really sure. This tends to create a lot of stress. Another thing that is made more difficult by missing documentation is feature design and work estimation. For every feature, you have to wade through the code trying to find the correct classes and methods to use.

As I explained above, you project your mental image of the system using the grammar of a programming language. The programming language is good at expression what is being done but what it's not so good at is explaining why. Often you make choices that might not seem to make sense to the reader of the code. This might even result in the person "fixing" the code. Having the reasoning of that choice documented in some way can be very important.

We also often tend to forget about documentation having the ability to aggregate information and make it simpler to read. It's often not just about whether the code is documented but also about how fast you can find the information you need. Say, for instance, you are in the situation I described above. You are a newcomer and you want to start doing something productive. The thing you could do is either go find some documentation, which is often scarce, or you could find someone who knows about how the system works. In the second option this person might then explain you the main architecture of the code and the guidelines for you to follow when developing or using the code, if that was what you asked. You feel satisfied and start working. Then a new guy comes in and does the same thing...

What I think is worth remembering here is that most people will ask the same questions, if that piece of information is missing. Being asked questions often means the required information is cumbersome to find or it does not exist at all. In this case you are using about X times the time you would have spent writing down the information you are being asked for, where X is the number of people asking.

Different types of documentation

You should not write documentation just for the sake of documentation. A piece of documentation has to always have a reader, otherwise it is useless. I like to categorize documentation into two groups: architecture and detailed. Note that we are talking about documentation targeted to the developer and not documentation like tool manuals and marketing material.

I would classify architecture documentation as the most important one because it describes the shape language for the code: the different sub-systems, coding conventions, threading rules, testing guidelines, patterns to use, non-functional requirements, etc. Overall, it works both as an introduction to the system as well as a guideline to using and modifying it. Architecture documentation is high level documentation used for controlling the overall direction of the project. It forms the boundaries, if you will, within which development is done. This is precisely why I think it's the most important piece of documentation: How can you be sure people go in the right direction if there is no direction defined?

Whether you require detail documentation is a bit more complicated. This includes documentation about individual classes, methods and sometimes algorithms too. My view on this is that you should not overshoot but neither should you neglect it.

Whether or not you require detail documentation depends on the type of code you are writing. If you are modifying an algorithm and you can be expected to understand its inner workings and you are able to understand the algorithm by reading the code, then you do not necessarily need additional documentation. Algorithms are usually contained in some manner and have few entry points. Some times, as was mentioned above, however, you might have made a choice when implementing the algorithm that might not initially make sense to the reader. This is where detailed documentation is important, to explain the "why" of those choices.

Now, if you are accessing an entry point of an algorithm and you have to understand the algorithm to know how to use the entry point then either you don't have clean code or you are missing documentation. To determine which is the case you should analyze whether it is possible to re-factor the entry point so that it is self explaining. It this proves too difficult, the entry point is missing documentation. There might also be some simple methods that get or set data whose names would become too complicated in which case documentation is also in order.

I have also personally heard comments about code documentation requiring too much discipline to work. It's just something that comes in your way when you implementing something and you have no time for anything extra. What is often forgotten, however, is that code is most of often shared property and multiple people are going to work on the code you have written. Implementing a new system requires design and implementation. Working on an existing one means understanding how it works, then designing and implementing the modification. Let me put that into two equations:

X + Y = time

X + Y + Z = time

The second equation is the one for modifying an existing feature and is very much impacted by the component Z that describes the time you have to use to learn the system. The more technical debt you leave behind the bigger Z will be for the next person coming to work on your code.

If we now break down Z into components Z1 and Z2. Z1 stands for the time used to learn what the actual code you are modifying does while Z2 describes the time you need to study related APIs. Clean code is the best way to minimize Z1 but Z2 might come from re-usable APIs like core engine code that you are incorporating into the existing code. To minimize Z2 you have to minimize the time it takes to learn what those APIs do.

The documentation process

Documentation is best written in small pieces. The difficulty in writing good documentation comes from the fact that you as the implementer are most likely not going to spot where there is information missing. This is where we come to the concept of code review.

Code reviews are the best method for finding places where documentations is required as the person reviewing the code should be able to understand what he/she is reading. If that is not the case, additional documentation or code cleanup is required. Personally I think both peer review and reviews done by the lead programmer are in order. In peer review you also share knowledge minimizing silent information, where some people know something others have no clue of.

There are multiple tools for technically performing code review. I have experience using a product called Review Board, which I can generally recommend. Regardless of the tools you use, code review should be built into the company culture. Choosing the tools is easy, getting the process running is the hard part.

Another thing that is a clear indicator of missing information is different people asking you the same questions time and time again. Documenting your answers will both save you the time of answering the same questions multiple times but also makes it possible for people to get to that information even when you are out of reach.

How should documentation be done, then? Personally I like wikis and code commenting. Wikis are good for documenting software architecture but code commenting is good for detailed information like API documentation. Also, you should exhibit some discipline. Documentation should be built into your way of working. Every feature should be reviewed and missing information should be incorporated either by cleaning the code, commenting the code or writing about it in the architecture documentation. The order is important. You should first consider cleaning and only do commenting if it proves too cumbersome and defeats the purpose. If the information is missing on a larger scale (which systems take part in managing the game world, for instance) then the architecture documentation should be updated.


Documentation requires discipline, but so does programming itself. It is indicated by the very process of using a well structured programming language to describe a system that is to work in a deterministic fashion to perform a certain set of tasks. Documentation should not be thought of as a necessary evil that is to be defeated by forcing everyone to write silly amounts of it. It should contain information that is difficult to describe otherwise, information that people need in order to be effective at what they do.

In my view, there is no single right way to perform documentation. Some people say it should all be incorporated into the code, some say there should be no commenting at all and clean code is enough while others like to have the whole set. My tip is that you should do what works best for you as a company. The bottom line being that documentation is about improving the efficiency of everyone in the company, it should not be there just for your nuisance.

Related Jobs

Activision Publishing
Activision Publishing — Santa Monica, California, United States

Tools Programmer-Central Team
Bluepoint Games, Inc.
Bluepoint Games, Inc. — Austin, Texas, United States

Senior Graphics (or Generalist) Engineer
Intel — Folsom, California, United States

Senior Graphics Software Engineer — Hunt Valley, Maryland, United States

Graphics Software Engineer


Thomas Happ
profile image
I was working in some code yesterday where the variables were all m_B, m_B1, B1, B2, p1, p1, cp1, cp0, E, P, etc. I asked my boss and it turns out it was written years ago by a Russian programmer and even if I did know what the variables stood for, they would be transliterated Russian words, anyway.

Chris Clogg
profile image
Here is my stab in the dark:

m_B: multiplayer Bot
m_B1: multiplayer Bot 1
B1: Bot 1
B2: Bot 2
p1: player 1
cp1: computer player 1
cp0: computer player 0 (neutral)
E: Empty server
P: Player (temp)

Robert Crouch
profile image
I am amused that you chose X, Y and Z (which is composed of Z1 and Z2) as variable names in your example shortly after extolling the virtues of descriptive variable names. Old habits die hard.

Let me use two different equations:

Design_Time + Implementation_Time = Total_Time
Design_Time + Implementation_Time + Learning_Time = Total_Time

As well as:

Learning_Time = LearningCode_Time + LearningAPI_Time

When you're writing it though, it's quick to just say X, Y, Z. I mean, hey, you're only using them once, for something small, and it's not so important.

My point is just that even when you're aware of the benefits, it's so easy to take that short cut just this once, for something simple that's going to be thrown away anyways. Then later that something simple becomes more relevant and ends up as a key piece of your infrastructure.

Andrew Grapsas
profile image
Yup. That's why I always call what I (and my engineering team) do "production code."

So they know they can't write throw-away, one-time use code. It's production code. It's going into production. Respect that.

Michael Parker
profile image
This whole situation sounds very strange and unprofessional. You've started a job without any direction or mentor. You're not told what to work on, or how to work on it. You have no colleagues to work with. You go ask the CTO where the documentation is?!! I mean come on... what's going on in this company?? There's far bigger issues than documentation!

Anyway... your point that you can replace face-to-face mentorship with documentation I disagree with. Every new hire asking the same questions - is that really a bad thing? Mentorship is about much more than simply explaining what a piece of code does - it's about using tools, practices, but also part of the social interaction that keeps employees happy. If your teammates aren't happy to talk to each other, then perhaps there is a larger issue in the office.

Secondly, I don't agree with your conclusion about "having clean code is not enough". You say this is particularly true for using 3rd party libraries, but isn't that up to the 3rd party? Also, if it's hard to use, then wrap it! Make an adapter or a facade. Make a class with a much simpler interface which delegates to it. Isn't that the best way to protect yourself from 3rd party API changes anyway? You mention internal engine with 3rd party-like calls - if you can't immediately use it, then it doesn't sound very clean.

Thirdly, you haven't mentioned automated test suites, which are often the best places to find some acceptance level tests which describe at a high level what particular classes do and how to use them, but also unit tests which set up dependencies and show you how to use code together. You talk about lack of code samples - thats exactly what acceptance tests are for!

Fourthly, yes it's difficult to develop a good "programming language grammar" as you call it - this is called a "ubiquitous language" in Domain Driven Design, and is a highly important part of working on shared code in a development environment.

Roberto Alfonso
profile image
You would be surprised at the amount of companies that just don't document, Michael. Just last week someone who started working with us 6 months ago asked me for a hand. Our healthcare product has growth charts, and the curves had to be updated, but there was no documentation, only the old 9 XML files and the schema. Digging into the very old SourceSafe we found the program that built the XML (which did it without a single reference to XML utilities, just by concatenating strings) but we didn't have the data files to feed it, only the resulting data. So, I just picked a few random values from the XML file and feed it to Google, along some keywords like BMI and growth chart, and found in the CDC the text files that were used to create the file, which allowed him to understand what each field meant, and how to transform it to accept data from the WHO.

When I started working as programmer here 10 years ago I had to rebuild the drug database knowing only how the final tables should look, but no examples, no data, nobody to explain me, and probably the worst, not even a program that created the tables.

Technically, developers don't need to document code, that's up to the designers. They should design the software, after all, including the workflow, the components, the API itself, and therefore and not even knowing the source code, even the documentation for each of them, while the developer should just sit down, read what the function receives and what should generate, and write the code to achieve it. It's kind of building a house: the bricklayers shouldn't write down how many bricks they used, or how much concrete, or where the pipes go, it should all be specified by the architect or the engineer.

Michael Parker
profile image
Your example of the program that built the XML - I would argue the problem is the terrible state of the code, not so much the lack of documentation. I would rather spend time cleaning up the code so it's sensible (and references XML!) rather than writing documentation.

Ideally, there should not be any need to document software. My current company does not document the code and code reviews actively work to remove code comments and embed the comments inside the code instead. Instead of documentation, we prefer:

* Clean readable code with expressive variables and function names, single responsibility etc (SOLID)
* Automated tests with in-place code examples which never go out of date
* Mentorship and teamwork to share experience within your codebase

But every company and situation is different. If legacy code is such as mess that refactoring it to a readable state is going to take a long time, then documenting the chaos can be sensible.

Don Moar
profile image
Thanks for the article Timo. I think documentation is an important part of any system.

I think code is too volatile to document. Time spent documenting the code is almost certainly wasted because implementations change too frequently. As Michael said, just use good programming techniques and let the code speak for itself. (This is a bit of a change for me compared with a few years ago, although I still like basic file and function header comments.)

On the other hand, the goals, purpose, design, usage, etc. of the system are much more likely to endure. Anything that is non-obvious from looking at the code but that is important to know when maintaining or extending the system should be documented. Time spent documenting that the system is intended to provide a certain set of high-level services, or run within a certain memory limits, or under certain time constraints, or with a certain UI standard, or by initializing a certain class, ... is worthwhile.

I don't think good documentation will eliminate mentoring and face-to-face discussions. Documentation allows new members of the team to get up to speed in a consistent fashion without having to rely on a particular person (or persons) who might be very busy at the moment or just out of the office for the day (or the week). Also, new people can act as reviewers of the documentation pointing out or even correcting for any "drift" that may have occurred.

Of course, this is just my opinion. The needs of your particular project, company, or industry may impose (or not) different requirements. I think that in the absence of any external requirements for more comprehensive documentation, this is a reasonable approach that tries to balance keeping the team moving forward today, and in the future.