Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?

[Jim Meyering]

Bruno Haible <address@hidden> wrote:
> The function descriptions are more important in the .h file than in
> the .c file. It's a basic economic principle, based on the fact that
> .h files are smaller and much easier to understand than the .c file.

Hi Bruno,

Most of the time, when I care about those comments, it's because
I'm reviewing the semantics of the function.  And often the comment
is incomplete.  If the comments were always guaranteed to provide
a complete and accurate description of the code, it wouldn't matter
as much.  Of course, it sometimes happens that the comment and code
get out of sync.  And when they're in separate files is makes detecting
such inconsistency even less likely.

Besides, hasn't the status-quo (in GNU code) always been that we put
comments as near the _code_ as possible?  At least in my experience
it has been.  The GNU Coding Standards document says this:
(in `Commenting Your Work'):

  ----------
     Please put a comment on each function saying what the function does,
  what sorts of arguments it gets, and what the possible values of
  arguments mean and are used for.  It is not necessary to duplicate in
  words the meaning of the C argument declarations, if a C type is being
  used in its customary fashion.  If there is anything nonstandard about
  its use (such as an argument of type `char *' which is really the
  address of the second character of a string, not the first), or any
  possible values that would not work the way one would expect (such as,
  that strings containing newlines are not guaranteed to work), be sure
  to say so.

     Also explain the significance of the return value, if there is one.
  ----------

Why should we change now?

Jim