On Mar 23, 2011, at 1:24 PM, Krzysztof Kosiński wrote:
2011/3/23 Jon Cruz <jon@...18...>:
- start with "/**"
- have the first sentence as a brief description, and be sure to end with a period '.'
- comment a function/method in the .h and not the .cpp (if it is in both)
...
Documenting in the .h is contentious. My opinion is: if the function is defined only in the header (inline), put the docs in the header. But if it's defined in .cpp, put the docs above the definition in .cpp, so documentation changes won't trigger extensive recompiles.
Not really. It hasn't been contentious in professional development for some time now.
First it only affects incremental builds, so that mainly leaves it to potentially affecting individual developers or incremental build systems. However the latter are usually automated and happily run often, so they don't care. And for developers, one would have to pull only the doc change and no other changes. For most any project with a noticeable velocity this is a rare occurrence.
More important is that such doc-only changes are extremely rare (perhaps once a quarter, if even that frequently). On the other hand the .h file is the public documentation of the corresponding compilation units, and should be kept in sync. One should be able to read just the .h and know how to use the code. Modularity and encapsulation are key to good modern software development (Brooks explains this well in his 20-year follow up to The Mythical Man Month), and keeping the .h to declare and the .cpp to define are main contributors to good encapsulation. Sacrificing things such as legibility and maintainability for the rare boost to odd builds is usually not worth it.
On the other hand, docs should be updated each and every time functions and methods change. Having them right next to each other aid in this maintainability and overall legibility. Professional developers have also found that having doc comments in the .cpp files leads more often to them becoming stale and outdated.
Also, a function or method declaration is a promise to others about the behavior of the code. Formalizing such promises with corresponding documentation is a very good thing. Developing habits to formalize promises early and to avoid arbitrary changes to the substance of a promise is also a very good thing.
I would add
- If there is a @file comment at the top, do not include the author
information in it - put it in a separate normal comment
Handy.
- Use /** */ and /// instead of /*! */ and //!
Yes, very much so. Among other things that keeps doc comments simple and consistent.
- For one-line documentation of class members, use ///< after the member
Yes (though I find this most useful for short comments. For longer ones a normal /** */ might be warranted. But there are usually less of those cases)
- Be careful to document what you are intending to, not e.g. the
Inkscape namespace
Quite important. I find it most useful to run a doxygen pass after doing some changes, and making sure what I thought I was doing actually shows up properly.