Sign in to follow this  

C++ comments---in .h or .cpp?

This topic is 3741 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

For documenting classes and functions, the standard is the .h file, since that correlates more closely with the code's interface layer. Users who just want to know what functions there are and what they do should be able to get that information without looking at the details of how the functions are implemented. Of course, documenting the internals of a function which have no externally visible effects should go in the source file.

(Cue a raft of links to people bellyaching about how comments are useless.)

Share this post


Link to post
Share on other sites
Quote:
Original post by Sneftel
(Cue a raft of links to people bellyaching about how comments are useless.)

Use descriptive names so comments are not needed as much.

Comments describing how to use it belong in the header file. I prefer a terse comment in the header, example uses in the unit tests, and descriptions in our wiki.

Comments describing how you implemented it belong in the implementation files, with design notes in a wiki.

Share this post


Link to post
Share on other sites
Comments are great. I like to add them on top of self documenting code (classes named correctly, along with functions and variables). Self documenting code like this requires less comments making life easier when you update or change things. It also reduces your need for external documents besides general overviews and such.

But yes, header files is the standard place for comments.

Share this post


Link to post
Share on other sites
Put them everywhere and take an hour/day to write external doc. Programmers are some of the worst people to document their work and when they do, it still sucks for clarity and conciseness, brevity and adaptability to the human condition for learning. Some of them need to go back and retake composition.

I'm appalled daily at the communication skills of programmers and other geeks.

Share this post


Link to post
Share on other sites
For me, most of the docs go in the header file. The exceptions are functions and implementation details.

In the case of functions, the brief description (I use doxygen. The "brief" description is a single line summary.) goes in the header, but the rest goes in the cpp. The reason is that the header file needs to be compact and concise. If each function declaration were accompanied by 5 to 20 lines of documentation, it would be impossible to find things.

Implementation details should not be placed with the public interface since the user should not need to be concerned with (or even aware of) them.

Share this post


Link to post
Share on other sites
Put documentations where (and only where) it applies and is helpful.

As such, you document how a class should be used in the header file (because a client should consumes a class's interface, not its implementation details).

As stated, use better names to reduce the amount commenting needed. You should ONLY comment things which the (header file) code isn't already saying out loud.

Comment implementation details that are somewhat non-obvious (to an experienced developer - aka YOU! or you a few months ago) in the implementation they apply to.

DO NOT REPEAT YOURSELF - Comment the general truths and usage of your project / framework in a central location - like a website, help doc, wiki or whatever.

There should be exactly 1 place that has the OFFICIAL info about some specific thing. And at most 2-3 more duplicate references or repetitions of that info. Prefer referring to existing documentation over copying it.

Share this post


Link to post
Share on other sites
I usually wait until I'm finished writing a source or header file before commenting it. Actually, the only reason I comment it at all is because I plan on open-sourcing everything of mine some day.

Share this post


Link to post
Share on other sites

This topic is 3741 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this