# 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.

## 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 on other sites
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 on other sites
So it would be better to embed UML and documentation into HTML rather than text and image files?

##### Share on other sites
Quote:
 Original post by GinkOn 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 on other sites
For documentation generated from source code I use Natural Docs.

For UML modelling I use UML Sculptor. Maybe it's not automatic, but you can make with it useful diagrams very easily by yourself.

##### 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 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 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 on other sites
Quote:
 Original post by GinkYeah 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 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.

1. 1
Rutin
49
2. 2
3. 3
4. 4
5. 5

• 10
• 28
• 20
• 9
• 20
• ### Forum Statistics

• Total Topics
633409
• Total Posts
3011722
• ### Who's Online (See full list)

There are no registered users currently online

×