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
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:
Then of course you can generate documentation for your engine and post it online as a link from your blog/forum.
L. Spiro
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.
- Wiki for Design Documentation and more.
- Task Manager for Project Management.
- Doxygen for Code Documentation.
- Git for Asset Version Control.
- WordPress for Web Portal + Blog.
- 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
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
Author
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 ;)
And by the way, doxygen can automatically generate UML diagrams for all your classes ;)
Author
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.
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
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
