C++: Where to write the code documentation: in .cpp or in .hpp files?

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

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

Solution 2

If you make a library, you typically distribute the compiled library and the header files. This makes it most useful to put documentation in the header files.

Solution 3

Again, both. As for the public documentation, it is nice to be in the .h with a format extractable with Doxygen, for example, as other commented. I like very much the Perl way of documenting things. The .pl (or .pm) file includes documentation in itself that can be extracted using a tool similar to what Doxygen does for C++ code. Also, Doxygen allows you to create several different pages, that allow you to include user manuals, etc., not just documenting the source code or API. I generally like the idea of a self-contained .h/.hpp file in the philosophy of literate programming.

Solution 4

Most importantly, are there any practical considerations that makes it more convenient to write it one way rather than the other way ?

Suppose that you want to add a clarification to one of your comments without changing the code. The problem is that your build system will only see that you changed the file, and unnecessarily assume that it needs to be recompiled.

If the comments are in the .cpp file, it will just recompile that one file. If the comments are in the .hpp file, it will recompile every .cpp file that depends on that header. This is a good reason to prefer having your comments in the .cpp files.

(E.g. the use of automatic documentation parsers and generators like Doxygen...)

Doxygen allows you to write your comments either way.

Solution 5

I personally like documentation in the header files. However, there are some that believe that documentation should be put in the source files. The reason being that when something changes, the documentation is right there reminding you to update it. I somewhat agree, as I personally have forgotten to update the Doxygen comments in the header when I changed something in the source files.

I still prefer the Doxygen comments to be in the header file for aesthetic reasons, and old habits are hard to change. I've tried both and Doxygen offers the flexibility of documenting either in source or header files.

View more solutions