Where should I put documentation comments? [duplicate]

Question

For usage information, it's nicer to put into the header. That's where people would look first.

The documentation is really successful if no one has to examine your .cpp file to figure out how the component should be used.

As far as I know, every time you change something in the .h file, it causes all files that have included that header file to be recompiled. For this reason, I put most of my comments in the .cpp files.

For C++, I put "documentation comments" in both the cpp and h.

The cpp contains the code, and has documentation comments on every main code element (classes, methods, etc) that describe them - typically with doxygen or Documentation XML comment format (although I don't tend to generate external docs, I find it useful to stick to a standardised format that can be extracted to external tools if/when I decide I want that). This is comprehensive documentation that explains exactly how a caller should use a method, and also any design details that will need to be understood by anyone intending to modify the code, so they understand the intent, "contract", and any important things to understand about the operation of the code. (I've written an addin for Visual Studio, AtomineerUtils, that makes creating and updating these comments quick and easy, so it's really not much effort to document things like this consistently and comprehensively)

My header is treated as a summary (both for the compiler and myself) - it uses a single-line // comment that briefly describes each method. This gives more information than the (hopefully relatively self-documenting) method/parameter names, but a lot less than the detailed documentation in the cpp. Think of it as a summary or reminder that saves you looking at the actual implementation to get enough details to use the method most of the time.

If you're using some sort of automatic documentation generator, comments should go wherever it tells you they should go.

Otherwise, I put general "this function does X" comments next to the function definition rather than the function declaration (unless, of course, the function is declared at its definition).

Because function declarations can be a bit bulky, putting documentation in the header file usually makes it much easier to view all comments pertaining to a given class at once, increasing the other developers' understanding of that class at a glance.

You should put your comments in the declaration of the files, i.e., in the header or interface file, the one ending with .h extension.

Probably, for distribution, you are going to ship the header files directly and the .cpp ones in binary form, i.e., not readable, so if you expect someone to read your comments, they should be inside the header file.

There are also implementation documentation, that only has its natural place in the .cpp file.

In any case, it is better to use a documentation tool, and learn the two or three Javadoc usefult tags that are so common used. You have to change the opening comment to /// or /**

//header.h
/** @brief About power()
    @see lpower
    @param x The base to power
    @param y The exponent, number of times to multiply base by itself
    @return x^y
*/
int power(int x, int y);

If you use a Doxygen, it will generate documentation from either, but if documentation appears in both the header and the implementation, the header takes precedent, so avoid duplication and document the header.

Also the header defines the user interface which is what a user of a class is interested in. Further if you deployed the code as a library or object code, the header is the only source the user will have access to.