Question

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