Jump to content
  • Advertisement

Archived

This topic is now archived and is closed to further replies.

RedRocket

Code Documentation.

This topic is 6173 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I''d like a few opinions. I''m working on a game project with a team of two other programmers. Myself and the project''s lead programmer designed the game''s classes and a thrid programmer recently joined us. We think we can hammer out the remaining code between the three of us. The issue is that while the code is decently commented, we never wrote any overall documentation (i.e. text/html files describing the classes in detail). I''m thinking that with only one other programmer we can simply bring him up to speed and not spend the time documenting our classes. Is this a really bad idea? If anyone have any experience or has an opinion on this issue I would appreciate your input.

Share this post


Link to post
Share on other sites
Advertisement
Guest Anonymous Poster
If it is generously commented then don''t bother documenting it if you have more than say 300k of code (not much compared to commercial games). The problem is that documenting your project should be done while you write the code (or, write the class, write the doc, write the class, write the doc, etc). You will run the risk of mis-documenting code you''ve left alone for a while and you might also grow tired of documenting such a large chunk all at once, leading to less-accurate documentation as you progress into the mass.

But you said that you''ve already commented it well. This should be enough for any programmer to climb on board within a week or so (*decent* documentation worth reading takes much much longer than that to prepare so weigh the time).

If you''re still worried, check out any of the available source code documenters out there like DOxygen (http://www.stack.nl/~dimitri/doxygen/). This reads your source code and generates HTML-based (fully searchable, linked, with drawn inheritance trees, etc) documentation. You will only need to change the formatting style of your comments and DOxygen will read it all (add things like @param, @returns, @defgroup, @ingroup, comments as /** */, or java-doc style, etc).

A final suggestion (although not highly recommended) is to switch to using the beta version of Visual Studio .NET. The new VS IDE comes with a source code documenter that generates great looking HTML documentation from normal source code (just like intelli-sense works). It looks unfinished at the moment, maybe even experimental, but it''s worth a look.

HTH

Share this post


Link to post
Share on other sites

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!