Jump to content
  • Advertisement
Sign in to follow this  
tufflax

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

This topic is 4024 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

Hey! I'm just wondering where I should put my C++ comments for documentation purposes---in the header or the source file? What's the standard?

Share this post


Link to post
Share on other sites
Advertisement
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
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!