Question

Where is it customary to write the in-code documentation of classes and methods?

Do you write such doc-blocks above the corresponding class/method in the header (.hpp) file, or within the source (.cpp) file?

Is there a widely respected convention for such things? Do most C++ projects do it one way rather than the other?

Or should documentation be written on the two sides (i.e. in the .hpp and the .cpp files), maybe with one short description one one side and a longer one on the other side?

Most importantly, are there any practical considerations that makes it more convenient to write it one way rather than the other way ? (E.g. the use of automatic documentation parsers and generators like Doxygen…)

Answer 1

Both:

• Describe the API design and usage in the header: that’s your public interface for clients.
• Describe the implementation alternatives / issues and decisions in the implementation: that’s for yourself – later – and other maintainers/enhancers, even someone reviewing the design as input to some next-gen system years hence.

Comment anything that’s not obvious, and nothing that is (unless your documentation tool’s too stupid to produce good documentation without).

Avoid putting implementation docs in the headers, as changing the header means makefile timestamp tests will trigger an unnecessary recompilation for client apps that include your header (at least in an enterprise or commercial library environment). For the same reason, aim to keep the header documentation stable and usable – good enough that you don’t need to keep updating it as clients complain or ask for examples.