Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

Tags:

c++

comments

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

like image 204
Nick Bolton Avatar asked Mar 28 '09 01:03

Nick Bolton


2 Answers

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!

like image 117
ypnos Avatar answered Sep 21 '22 03:09

ypnos


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

like image 20
Tom Avatar answered Sep 22 '22 03:09

Tom