How to document a game engine + game development?

i'm intrested in this topic too, but i think it's against programmers nature to write documentation

http://lspiroengine.com

You can open a blog and forum as I have done.
For documenting code itself, I use Doxygen. For example:

/**
* Called when the state is just created. Use this to initialize resources.
*
* \param _pgGame Can be accessed for whatever game-specific information needs to be
* obtained.
* \param _ui32State The current state identifier (the same class could
* then be used for multiple states if they are similar enough).
* \param _ui32PrevState The identifier of the previous state.
* \param _uptrUser User-defined data passed to the state. How this is used is entirely
* defined by the state. Examples of use:
* #1: Which map to load in a game state.
* #2: Which tutorial page to show in a tutorial state.
* #3: Used as a pointer to data containing a lot of state-specific information such as
* map file to load, previous state of the player, etc.
*/
LSVOID LSE_CALL CModelState::Init( CGame * _pgGame, LSINT32 _ui32State, LSINT32 _ui32PrevState, LSUINTPTR _uptrUser ) {
}

Then of course you can generate documentation for your engine and post it online as a link from your blog/forum.


L. Spiro

How to document a game engine + game development?

My game engine + game, two projects solution, got 2500 lines today. I already begin to forget how I did some stuff. I need first of all:

1. To find a way HOW to document my engine architecture.
2. Then to reread the whole code and document what is done so far, before it gets more complex.

UML diagrams could help for high level design. All the cool stuff we learned in class I might apply now. Finite state machine would be nice. Sequential diagrams are nice too.

Sometimes just code comments is enough documentation, for example for some method.

For some things I feel like writing explanations in pages.

So the way I imagine this is a pdf file with lots of UML diagrams, code examples and text explanations here and there. Like a reference for my engine. Imagine there is Contents as in a book, and you have stuff like UI, IO, Managers and then in Managers you have chapters like EffectsManager, LevelManager, BulletsManager and so on... I would spend two weeks on something like this, including research on HOW to do it first of all. It would make things so much easier when this game engine hits 10 000 lines and more.

Not to mention how easier it would be to get comments about the engine. I can give that document to a pro game developer, he can read the whole in less then hour, and throw some suggestions.

I have not done anything like this before so give me some opinions guys.

Thank you

Hi calculemus1988,

Documentation is very important and often overlooked.I commend you for acknowledging its value early in your project. With that said, its possible that you may have a need to do more than just document the code. Heres a list of Web Applications and Services I'm using for the development of the Super 3D Game Platform.

1. Wiki for Design Documentation and more.
2. Task Manager for Project Management.
3. Doxygen for Code Documentation.
4. Git for Asset Version Control.
5. WordPress for Web Portal + Blog.
6. Mibbit for WebIRC Chat.

You can also include a Forum such as PHPBB. However, what I usually do is start Topics in other popular Forums such as GameNet, TheGameCreators, and many others.

Good Luck to you.

Yep, doxygen or similar documentation generation tools are pretty much the way to go for creating documentation for you code, they work very intuitively and create a very clean overview of your code, as long as you document the code itself properly and adhere to a correct comment format

Be sure to think of documentation right at the start of a project, especially if it's probably going to turn out to be a rather large one
It will save you the trouble of having to go back and document all of your existing code, and will make the project in general much more manageable

What about UML diagrams? I would rather draw one page big diagram for architecture description rather than writing one page text.

UML is ok to document the general architecture of your engine, but you'll never get the specifics of each component in there
And by the way, doxygen can automatically generate UML diagrams for all your classes ;)

Nah, Visual Studio already does that. I meant UML in the sense doing finite state machine diagrams, sequential diagrams and that kind of stuff for modelling behavior of some parts of the engine, not just structure.

Also have a look at:
Bitbucket
Trac
DokuWiki
or BitNami for simple try out

Nah, Visual Studio already does that. I meant UML in the sense doing finite state machine diagrams, sequential diagrams and that kind of stuff for modelling behavior of some parts of the engine, not just structure.

I'm not directly aware of any programs which can aid you in doing some more advanced UML-related stuff, I do know my OOP professor provided me with some UML tools for Java last year, but you still had to draw out most of your behavior diagrams manually, which can become pretty time consuming even for smaller projects

I'm writing an engine myself at the moment and I use doxygen for code documentation, issue tracking software to create a priority-based 'job list' (can include feature implementations and bug fixes) so I can manage my development process (I know issue trackers aren't exactly meant for this, but it works perfectly for me) and a small blog just to comment on some development milestones and overall process

After about 1,5 years of development I can say that I haven't experienced a need for more documentation than all of this, but I assume this is not the same for everyone

For documenting code, I use Doxygen. I've never used UML, but for some of the state diagrams that I wanted to show in my API documentation, Doxygen has built-in support for dot/dia, which can make some visually appealing directed graphs. Most other images I've needed to embed I create in an image editor and store alongside my code (usually in the project_name/docs/images/ directory in my repository), and I use the appropriate Doxygen tags to include them where needed.

For documenting development in general, nothing has beat a notebook + pencil for me. I use it for all sorts of things: brainstorming new features, mocking up interfaces, writing down notes from whatever topic I'm researching, concept sketches, working through prototypes, you name it. It's just so damn versatile and generally easier to get ideas out of my head on something more permanent than if I tried using some sort of software. The only exception is I might open up a mind mapping tool (like MindNode on OSX) if I'm doing some far out, non-linear brainstorming session, kinda like the ones where you have a single idea in the middle and branch out in all directions with related and tangential ideas based the initial topic.

Documentation is good, and the tools that have been suggested will certainly help you; but you need a long-term solution. 2500 lines is pretty small, all things considered; even simple games can break into the 100,000 line region, and top-end complex games often have millions of lines of code. Past a certain point, documentation alone isn't worth much, because you can't document 4 million lines of code efficiently and read the documentation and still understand the code; too much to cram into one brain!

The solution is to think in terms of abstractions, sometimes referred to as "chunking." Instead of trying to memorize all of the details of every part of your program, think in terms of systems: collision detection, physics, rendering, animation, game logic, user interface... think about how these systems interact as large portions, rather than about the line-by-line nature of each implementation. This takes a lot of practice and experience, but it's a good thing to work towards.

At work, I deal with a codebase so large I don't think anyone has actually collected statistics on how many millions of lines of code we have; but many of us cope with a large swath of that codebase every day, and we can do so because we're not lost in the weeds of individual functions and classes, but rather see things as large "black boxes" interacting. Occasionally we have to dig into two or three of those boxes at a time to figure out the details of an interaction, but that's still a lot easier to manage than trying to keep the entire mass in our minds at once.

That said, you'll find that as you go, keeping track of ever-increasing code sizes becomes easier as well. The combination of chunking and just plain old experience-stretched memory capacity will take you a long way.

Am I really the only one that's comfortable just winging it and putting a little // or /* */ here and there?

I am going to contradict my own practices or the common sense but my experience tells me it's more important to focus on good code and to write documents than documenting the source code via doxygen.

As for good code replicate the same patterns as much as possible. i.e. Creating a new texture/material/sound/script should follow a similar mechanism so once people understand how to create an object, they can create what they want regardless of the object type. Use the same syntax, use meaningful variable names, use some kind of notation to distinguish members, parameters, global variables. Nothing special but if the code is bad code doxygen won't make it better.

I use doxygen and last time I generated the documentation for an huge C++ codebase tried to produce an rtf/pdf file and it turned out to be 2000+ pages. So yes, I definitely use doxygen but when things get quite complex it is of no or little use to have tons of (web)pages documenting what every single method does unless you have something pointing at the big picture. A document is good because you can't write a poem at the beginning of each file!

So in the meantime every time I added a significant feature I wrote a few pages about that. Guess what? Now I have a manual... and even if I'm behind the last developments I have a 140 pages user's manual clearly explaining how to use that engine. Also if you are in a small company or even more if you work alone it might be possible to have to stop development for a while. Without proper documents starting again might be a pain.

Third suggestion: write examples for every sigificant feature, comment them and write a brief description of it. This will also help you refactoring or testing single parts of the engine.

So one day you hire somebody or sb is using your technology... well give him the manual+examples and he'll be fine.

Doxygen is a valuable resource when it comes down to have a quick reference for understanding how a class/method has to be used, documents are valuable when it comes down to understand how your technology works.

I find StarUML extremly useful but alas as someone already said writing documentation goes against our nature. So I usually just write a few lines before the function like who calls it and stuff. And some code comments on more complicated parts.
There were about 10K times I can remember thinking "God wish I wrote comments here!"

Am I really the only one that's comfortable just winging it and putting a little // or /* */ here and there?

Yes.

Because Doxygen or similar are required by many companies, and they are simply the right thing to do for any serious project. Besides, in all of the open-source code I have ever seen so far with one exception, variable names have no meaning, or are otherwise not self-descriptive.

int build_huffman( zhuffman * h, uint8 * s, int n )
Okay, n is commonly used for a total and there is a pointer before it so it is clearly the length of the array.
Care to tell me what s is?

I encountered this just last night and had to look at what was being passed to the function to determine what it was, because inside the function every other variable was just another single-letter slop.
int c; // Oh, that is helpful. Now I know exactly how this is going to be used later in the function. Sigh.
The code had NO comments. Not inside functions, not above them.


The programmers who seem to think documentation is meant to be sloppy are also sloppy programmers. It all boils down to being lazy.

I not only fully document my code and functions, I also give meaningful and self-descriptive names to every variable (except iterators i, j, and k).
Stop being lazy and spend the appropriate time to make your code complete.


L. Spiro

For the curious, you can see how I comment my code here.

[/shameless_plug]

I am going to contradict my own practices or the common sense but my experience tells me it's more important to focus on good code and to write documents than documenting the source code via doxygen.

For me personally, I don't view it as an either/or sort of thing, In my library that I've been building up, I use doxygen for both purposes. In my top level header that I use to include commonly used components, I use doxygen's @mainpage and @section tags to write the high level overview that you describe. It hits on the major components of my library, how to use them in the common case with code snippets and cross-references to the actual API documentation. This pretty much serves as my quick start "user's manual". Granted, I'm the only one working on the code base at the time, but it's written in such a way that if anyone else happens to work on it in the future, they can read the doxygen main page that's generated and get a pretty good overview of how to use the code base.

All the other documentation is for what you'd typically expect to see generated from doxygen, that is to say descriptions of classes, methods, free functions, user types, etc. I probably go into more detail than your average developer, going to great lengths to describe what state things need to be in to successfully use a part of the API, the valid range of values for methods/functions, what exceptions are thrown and why, the interactions of various components, etc. I don't claim to be perfect in my coverage, but I do my best to be as comprehensive and accurate as possible because I want my users to not have to make assumptions or second guess how to use the APIs I write. If people are tearing their hair out debugging my library and stepping through the code all because I was too lazy to give them adequate documentation, then I've just failed as a library developer. At least, that's my opinion.

I will agree though, that latter bit of documentation can be next-to-useless to someone who has no clue as to how things are structured from a higher level just due to the detail it goes into. And that's what I hope to mitigate with the doxygen main pages I write.

I personally use Visual Studio and use the built in XML exporter and have it set up to export the comments so any method/class etc without an XML document throws a warning in the compiler. Right now I just use the raw XML to view my API but you could easily write an XSD or another parser to make a nice looking API documented.

For me personally, I don't view it as an either/or sort of thing, In my library that I've been building up, I use doxygen for both purposes. In my top level header that I use to include commonly used components, I use doxygen's @mainpage and @section tags to write the high level overview that you describe. It hits on the major components of my library, how to use them in the common case with code snippets and cross-references to the actual API documentation. This pretty much serves as my quick start "user's manual". Granted, I'm the only one working on the code base at the time, but it's written in such a way that if anyone else happens to work on it in the future, they can read the doxygen main page that's generated and get a pretty good overview of how to use the code base.

I had a coworker using doxygen that way and it worked fine. My personal taste is to fire a word processor and write a document but it doesn't matter what you use.

All the other documentation is for what you'd typically expect to see generated from doxygen, that is to say descriptions of classes, methods, free functions, user types, etc. I probably go into more detail than your average developer, going to great lengths to describe what state things need to be in to successfully use a part of the API, the valid range of values for methods/functions, what exceptions are thrown and why, the interactions of various components, etc. I don't claim to be perfect in my coverage, but I do my best to be as comprehensive and accurate as possible because I want my users to not have to make assumptions or second guess how to use the APIs I write. If people are tearing their hair out debugging my library and stepping through the code all because I was too lazy to give them adequate documentation, then I've just failed as a library developer. At least, that's my opinion.
[/quote]
I think when it comes down to documentation and comments better one word more than one word less. Sometimes code is documented in a lazy way and I hate it. Why sb should bother reviewing the code if the author was so lazy he didn't even spend two seconds to add a meaningful comment?