Including commented Class declaration in implementation file

Question

Hi All,
Everyone knows the advantages of a more readable code. So in order to make my code more readable what i do normally is include the commented class declaration in the implementation file of that class.
This way i need not have to browse through various include directories to go to the definition.
So, Is this a good practice or just over-documentation?
If there is some standard technique, plz let me know.
EDIT:
Is there a way to migrate to class declaration from implementation in Vim ?
Except opening it in new buffer.

Thanks

Answer 1

This does not help a lot, because when class definition is bigger than one screen, your colleagues will have to scroll up to get to the declaration. Modern IDEs are very good in locating the declaration so IMHO this is useless.

The only thing which really matters sometimes is that you put the access identifier in the comment when you define the function. This really saves time for someone trying to understand the code.

Something like this is enough:

//private
void Car::ReplaceDriver(const std::string & NewDriver)
{

}

Answer 2

This is actually counter-productive, because now you have to change three locations instead of two when modifying class declaration, and one of these locations won't be checked by compiler to catch any mismatches.

Also, in large and quickly-evolving projects comments always get obsolete, so they cannot be trusted.

All modern IDEs can help to access class declaration from class implementation in a number of ways, all of which are more convenient than scrolling to the top of file and then back.

As an alternative, consider using an auto-documentation tool such as doxygen. Doxygen can be told to include entire class declarations in the documentation -- with syntax highlighting, line numbers and links to the source files. You can include a doxygen pass in your build process and always have an up-to-date code reference.

Answer 3

I'd consider it over-documentation and have never seen it elsewhere. When modifying the class the comments will be out of sync quickly (or looking there you are never sure).

Not sure what environment you use, but when looking for a declaration, I normally use a function of the editor (on Mac Xcode and Windows VisualStudio you can right-click something and then jump to it's definition or declaration).

Answer 4

This breaks the DRY principle : you have to maintain the comments when you change the declaration.

And it will not help a lot read your code.

As they say (from memory) : "If the code and the comments tell different stories, they're certainly both wrong."

What will help is :

• make sure your class declaration in the header is well documented and/or pretty clear about the class usage : that's where most of the users of the classes will look first because that's the "manual" of your class (be it comments or explicit functions);
• write those comments in a way telling your intention, not what it will do exactly : the intention is what it should do, not what it does (if it's buggy) -- that way you give clues to other people (or yourself later) to fix bugs in your implementation because they can understand what you tried to do;
• don't report your header comments in your definition file (cpp) because it will be redondant!
• write comments in the definition code where you need to tell the intention and where what you do might not be obvious;
• if possible, replace comments in implementation code by real code (function or class) : you can often encapsulate a code block in a function with an explicit name or the result of an operation in a variable with an explicit name -- programmers will more thrust executed code than unclear comments....