Jump to content
  • Advertisement
Sign in to follow this  
squicklid

Documenting Classes

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

Should I be documenting functions in the class definition or in the source file... LIKE THIS: ----------
//////////////
// Monkey.h //
//////////////

class Monkey
{
public:
    // gives the monkey feathers.
    // featherLength - the length of feathers in metres.
    // featherColor  - 24 bit color for feathers
    // returns the monkeys reaction to the transformation
    REACTION addFeathers(int featherLength, DWORD featherColor);
}



OR THIS: --------
////////////////
// Monkey.cpp //
////////////////

// gives the monkey feathers.
// featherLength - the length of feathers in metres.
// featherColor  - 24 bit color for feathers
// returns the monkeys reaction to the transformation
REACTION Monkey::addFeathers(int featherLength, DWORD featherColor);
{
}



[Edited by - squicklid on January 19, 2006 6:21:42 PM]

Share this post


Link to post
Share on other sites
Advertisement
That's not documenting, that's commenting.

Some people are comment fascists, demanding that every argument be commented, along with all preconditions and postconditions.

Personally, I think where preconditions may cause a fail the should be noted (and probably assert'd anyway) and postconditions (return ranges) should also be commented.

I also think that any algorithm should be briefly explained in comments along with the code that implements it. Mathematical formulae in particular.

Write your comments as if the person reading them has NO knowledge of what your function is supposed to do. Your example is good in this regard - I also often (not always) comment both in the body and header, unless the function is self-explanatory.

Share this post


Link to post
Share on other sites
If you're going to comment your classes, use Doxygen style or similar. Even if you're not planning to generate Doxygen documentation, it's an easy and standard style to follow.

Also, don't make the mistake of assuming that documenting all your classes is the same as documenting the internals of your application.

Share this post


Link to post
Share on other sites
You can find doxygen here. Doxygen is good.

And to answer your question. I put a one line description (the "brief" description) with the declaration, and the rest goes with the definition. That keeps the header files uncluttered so I can find stuff quickly.

I would document your code like this:

Monkey.h

//! This class represents monkeys.
class Monkey
{
public:
//! Gives the monkey feathers. Returns the reaction.
REACTION addFeathers(int featherLength, DWORD featherColor);
};



Monkey.cpp

//! This function gives the monkey feathers ... blah blah blah
//! blah blah blah blah...
//!
//! @param featherLength the length of feathers in metres.
//! @param featherColor 24 bit color for feathers
//! @return the monkeys reaction to the transformation
REACTION Monkey::addFeathers(int featherLength, DWORD featherColor)
{
}


Share this post


Link to post
Share on other sites
Quote:
Original post by kpanghmc
I think a better question is: why are you putting feathers on monkeys? :)


"Impossible Creatures" maybe?

Anyway, Microsoft Visual Studio 2005 has got a very nice documentation feature built into it. Check this out. Personally I'd prefer "documenting" the code in declaration (header file), because any other clients that use the header will also be able to see them. e.g. if you ship a library, it's more likely that you ship headers instead of source files. So... commenting in header is a better idea, IMO.

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!