Re: place comments in C++ .h or .cc files?

From: James Dennett (jdennett_at_acm.org)
Date: 02/18/04 

Date: Wed, 18 Feb 2004 07:50:20 -0700

Francis Glassborow wrote:
> In message <c0unua$rl9@dispatch.concentric.net>, Gianni Mariani
> <gi2nospam@mariani.ws> writes
>
>> Digital Puer wrote:
>>
>>> jeffc wrote:
>>>
>>>> "Digital Puer" <digital_puer@hotjail.comet> wrote in message
>>>> news:c0u1vg$1ba$1@daisy.noc.ucla.edu...
>>>>
>>
>> ... snipola
>>
>>> Suppose I'm providing the implementation .cc files as well.
>>> Should I just cut-and-paste the same comments for each
>>> method API from the .h files (and have additional comments
>>> in the body of the methods)?
>>
>>
>> Only if you want a maintenance head-ache. At most if a method is
>> commented in the header you can put a reference saying - see the header.
>>
>> If you have a well documented header (preferably using doxygen), you
>> don't need to repeat them and it will be bad because when changes are
>> required you'll need to edit all instances of the comment which is
>> prone to error.
>>
>> Or is there a higher expectation?
>
>
> It isn't the purpose of comments to fully document code. Comments should
> highlight elements that cannot be correctly expressed in code. The
> problem with comments in headers is that every time you touch a header
> all translation units that include it have to be recompiled.

True with most simple build systems, but a more advanced
build system could avoid this -- it's not hard to tell when
the only change in a header is in comments.

> For student
> level programs that does not matter, for interpreted languages (such as
> Java) it is irrelevant but for fully compiled languages used for large
> projects (with perhaps more than 500,000 loc) recompilation can be a
> significant problem and there is a limit to how many coffee breaks you
> can take in a day.

But in real programming jobs there are almost always other
things you can be doing if compilation takes a few minutes:
coding time is but a small part of the job.

For hobby code, recompilation time is rarely a big problem
(although I do have to curb my urge to over-use templates
when prototyping code in C++, otherwise my build times do
quickly become long enough to reduce my productivity).

> Keep comments succinct and to the point, do not change them unless you
> are changing the header in some other way. Write proper documentation as
> something else.

I'd disagree with this. The comments are often the most
valuable part of the header file, and in most situations
it is folly not to maintain them for fear of triggering a
rebuild. This is true for most projects with which I've
worked, and they are generally in the 1 million line+
range -- only one project was such a pain to rebuild that
we had fear of touching header files, and that clearly
indicated a problem managing dependencies (which ironically
might have been lessened had the documentation in the
header files been better).

If I could be more idealistic, maybe I wouldn't advocate
using C or C++ headers as the best places to document interfaces.
In my experience of commercial software development, however,
putting the documentation right in the header, where the compiler
gets _its_ view of the interface, gives the only realistic
chance that developers will keep the documentation up to date.

-- James.

Relevant Pages

  • Re: Strings again :(
    ... All SQL documentation that specifies LPSTR/LPCSTR is erroneous. ... The header files for all ... WORD cbBufMax = 2000 * sizeof; ...
    (microsoft.public.vc.mfc)
  • Re: where is a copy of atlstr.h ??
    ... program for Visual Studio parks things in terms of directories, ... your expectation that Microsoft "documents this" is unreasonable. ... would have carry documentation for many previous versions of Visual Studio. ... or ATL header files are present on your computer. ...
    (microsoft.public.vc.language)
  • Re: Managing a project as it scales
    ... If you have ever once printed out a listing so you could circle the braces to figure out ... but braces should follow a methodology that is easy to read. ... Rarely is it valuable to maintain external documentation, ... Even the message handlers get procedure header blocks. ...
    (microsoft.public.vc.mfc)
  • Re: Bug in geometry package?
    ... still plenty of room for a footer and header. ... Would you mind pointing out where the documentation states this? ... discussion group whether they know any personal information about the ...
    (comp.text.tex)
  • Re: Why has the Metrowerks sign been taken down?
    ... I worked on Mac OS X since DP4 came out. ... I asked questions on email lists when I needed. ... The documentation issue is probably the single most universal complaint ... the quality of said header ...
    (comp.sys.mac.programmer.codewarrior)