Sign in to follow this  

Documenting Classes

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

This topic is 4380 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.

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