Jump to content
  • Advertisement
Sign in to follow this  
Gink

Documenting Code

This topic is 4818 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

On a real project, what type of documentation would be provided by source code so that a user would be able to understand how to use the code? Would it just be documented in the source files or would there be text files and UML charts etc?

Share this post


Link to post
Share on other sites
Advertisement
Obviously it depends on the processes in place for the team that makes the project. Some teams will have more rigorous procedures than others.

One thing you might consider, is using doxygen to generate documentation from the comments in the source code. For example, I put comments like these before every function, doxygen then extracts these comments, and makes HTML documentation for the project.





//=========================================================================
//! @function TerrainChunkNode::QueueForRendering
//! @brief Add the terrain chunk to the render queue
//!
//! @param queue [in] Render queue to add the chunk to
//!
//=========================================================================
void TerrainChunkNode::QueueForRendering ( Renderer::RenderQueue& queue )




Share this post


Link to post
Share on other sites
So it would be better to embed UML and documentation into HTML rather than text and image files?

Share this post


Link to post
Share on other sites
Quote:
Original post by Gink
On a real project, what type of documentation would be provided by source code so that a user would be able to understand how to use the code? Would it just be documented in the source files or would there be text files and UML charts etc?

If you're using any of the Visual-Studio-.NET languages, you should strongly consider using the XML-style comments. They're immensely helpful, and documentation tools like nDoc generate very pretty and readable documentation from them.

UML documentation can be automatically generated with enterprise-level tools these days. One choice is Enterprise Architect, though many (myself included) don't like it because of the clunky user interface.

Share this post


Link to post
Share on other sites
Say I have a 10-20 line simple algorithm, if I was to present this code to someone should I even use UML diagrams and if so, would it be an Activity Diagram?

Share this post


Link to post
Share on other sites
I think that for small things such as algorithms UML is not usefull. I often use UML to show the general structure of the program, and I think that's what it's ment to do.

Share this post


Link to post
Share on other sites
Yeah I thought it was kind of ridiculous to be using UML for something this small, so the only documentation I would need is good commenting basically?

Share this post


Link to post
Share on other sites
Quote:
Original post by Gink
Yeah I thought it was kind of ridiculous to be using UML for something this small, so the only documentation I would need is good commenting basically?


Yes, as far as I'm concerned.

Share this post


Link to post
Share on other sites
UML shouldn't be used as a code documentation tool, as in what functions do and what-not. UML is used to describe/design systems, their components, and the interactions between those components. So, at the source level, something like Doxygen would be useful. However, for large projects with many different components, supplying UML diagrams would be extremely useful in explaining how the system works.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • 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!