• Announcements

    • khawk

      Download the Game Design and Indie Game Marketing Freebook   07/19/17

      GameDev.net and CRC Press have teamed up to bring a free ebook of content curated from top titles published by CRC Press. The freebook, Practices of Game Design & Indie Game Marketing, includes chapters from The Art of Game Design: A Book of Lenses, A Practical Guide to Indie Game Marketing, and An Architectural Approach to Level Design. The GameDev.net FreeBook is relevant to game designers, developers, and those interested in learning more about the challenges in game development. We know game development can be a tough discipline and business, so we picked several chapters from CRC Press titles that we thought would be of interest to you, the GameDev.net audience, in your journey to design, develop, and market your next game. The free ebook is available through CRC Press by clicking here. The Curated Books The Art of Game Design: A Book of Lenses, Second Edition, by Jesse Schell Presents 100+ sets of questions, or different lenses, for viewing a game’s design, encompassing diverse fields such as psychology, architecture, music, film, software engineering, theme park design, mathematics, anthropology, and more. Written by one of the world's top game designers, this book describes the deepest and most fundamental principles of game design, demonstrating how tactics used in board, card, and athletic games also work in video games. It provides practical instruction on creating world-class games that will be played again and again. View it here. A Practical Guide to Indie Game Marketing, by Joel Dreskin Marketing is an essential but too frequently overlooked or minimized component of the release plan for indie games. A Practical Guide to Indie Game Marketing provides you with the tools needed to build visibility and sell your indie games. With special focus on those developers with small budgets and limited staff and resources, this book is packed with tangible recommendations and techniques that you can put to use immediately. As a seasoned professional of the indie game arena, author Joel Dreskin gives you insight into practical, real-world experiences of marketing numerous successful games and also provides stories of the failures. View it here. An Architectural Approach to Level Design This is one of the first books to integrate architectural and spatial design theory with the field of level design. The book presents architectural techniques and theories for level designers to use in their own work. It connects architecture and level design in different ways that address the practical elements of how designers construct space and the experiential elements of how and why humans interact with this space. Throughout the text, readers learn skills for spatial layout, evoking emotion through gamespaces, and creating better levels through architectural theory. View it here. Learn more and download the ebook by clicking here. Did you know? GameDev.net and CRC Press also recently teamed up to bring GDNet+ Members up to a 20% discount on all CRC Press books. Learn more about this and other benefits here.
Sign in to follow this  
Followers 0
calculemus1988

How to document a game engine + game development?

20 posts in this topic

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
0

Share this post


Link to post
Share on other sites
i'm intrested in this topic too, but i think it's against programmers nature to write documentation :D
0

Share this post


Link to post
Share on other sites
[url="http://lspiroengine.com/"]http://lspiroengine.com[/url]

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

[code]/**
* 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 ) {
}[/code]

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


L. Spiro
1

Share this post


Link to post
Share on other sites
[quote name='calculemus1988' timestamp='1314538707' post='4854721']
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
[/quote]

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 [url="http://s3gp.hpquest.com"]Super 3D Game Platform[/url].

[list=1][*] [url="http://www.mediawiki.org/wiki/MediaWiki"]Wiki[/url] for Design Documentation and more.[*][url="http://www.mantisbt.org/"]Task Manager[/url] for Project Management.[*][url="http://www.stack.nl/%7Edimitri/doxygen/"]Doxygen[/url] for Code Documentation.[*][url="http://git-scm.com/"]Git[/url] for Asset Version Control.[*][url="http://wordpress.com/"]WordPress[/url] for Web Portal + Blog.[*][url="http://mibbit.com"]Mibbit[/url] for WebIRC Chat.[/list]
You can also include a Forum such as [url="http://www.phpbb.com/"]PHPBB[/url]. However, what I usually do is start Topics in other popular Forums such as [url="http://www.gamedev.net/topic/605917-c-concept-3d-tool-games-togs-needs-you"]GameNet[/url], [url="http://forum.thegamecreators.com/?m=forum_view&t=155919&b=22"]TheGameCreators[/url], and many others.

Good Luck to you.
1

Share this post


Link to post
Share on other sites
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
1

Share this post


Link to post
Share on other sites
What about UML diagrams? I would rather draw one page big diagram for architecture description rather than writing one page text.
0

Share this post


Link to post
Share on other sites
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 ;)
0

Share this post


Link to post
Share on other sites
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.
0

Share this post


Link to post
Share on other sites
Also have a look at:
[url="https://bitbucket.org/"]Bitbucket[/url]
[url="http://trac.edgewall.org/"]Trac[/url]
[url="http://www.dokuwiki.org/dokuwiki"]DokuWiki
[/url]or [url="http://bitnami.org/stacks"]BitNami[/url] for simple try out
1

Share this post


Link to post
Share on other sites
[quote name='calculemus1988' timestamp='1314619923' post='4855033']
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.
[/quote]

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
1

Share this post


Link to post
Share on other sites
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.
1

Share this post


Link to post
Share on other sites
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 [i]and[/i] read the documentation [i]and[/i] 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.
2

Share this post


Link to post
Share on other sites
Am I really the only one that's comfortable just winging it and putting a little // or /* */ here and there?
1

Share this post


Link to post
Share on other sites
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.
1

Share this post


Link to post
Share on other sites
I find [url="http://staruml.sourceforge.net/en/"]StarUML[/url] 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!"
0

Share this post


Link to post
Share on other sites
[quote name='Kobo' timestamp='1314895081' post='4856363']
Am I really the only one that's comfortable just winging it and putting a little // or /* */ here and there?
[/quote]
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.

[code]int build_huffman( zhuffman * h, uint8 * s, int n )[/code]
Okay, [i]n[/i] 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 [i]s[/i] 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.
[code]int c; // Oh, that is helpful. Now I know exactly how this is going to be used later in the function. Sigh.[/code]
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
1

Share this post


Link to post
Share on other sites
[quote name='undead' timestamp='1314905529' post='4856428']
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.[/quote]

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.[i] [/i]If people are tearing their hair out debugging [i]my [/i]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.
1

Share this post


Link to post
Share on other sites
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.

1

Share this post


Link to post
Share on other sites
[quote name='romer' timestamp='1314934048' post='4856576']
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.
[/quote]
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. :)

[quote]
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.[i] [/i]If people are tearing their hair out debugging [i]my [/i]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? :angry: :angry: :angry:
0

Share this post


Link to post
Share on other sites
Wow so many comments, it will take me like a month to absorb everything said here. Will take it slow and learn a bit each day.
0

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now
Sign in to follow this  
Followers 0