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

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


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
{
}


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

##### 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 on other sites
I think a better question is: why are you putting feathers on monkeys? :)

##### 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 on other sites
So where can I find the doxygen style?

##### 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 transformationREACTION Monkey::addFeathers(int featherLength, DWORD featherColor){}

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