Should I comment the declaration or the definition in C++?

Question

Which is more practical to comment, the declaration (in the header file) or the definition (in the source file)? Maybe I should comment both, or comment neither and put it all in a separate file...

Answer 1

You should completely document the header file with highest priority.

Comments in the definition should be concentrated on implementation details, while header comments should be concentrated on the interface.

A third source of documentation, as you suggested, is useful as well. It should describe the overall concept.

A big plus of commenting header files is that you can create documentation automatically from them if you adhere to some simple syntax. Say hello to doxygen!

Answer 2

I want to add to ypnos's answer:

Where your comments go depends upon who your audience is. Thinking about your code as being closed-source helps in this regard: maintainers get to see the implementation, customers/users only get to see the interface. If the comment is necessary for users, it must go in the interface. If the comment is only relevant to the given implementation, it probably only needs to go into the implementation (but not necessarily, depending on your audience).