[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Bug-gnulib] putting identical comments in both .c and .h files: wha
From: |
Jim Meyering |
Subject: |
Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think? |
Date: |
Wed, 27 Nov 2002 14:51:41 +0100 |
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
- Re: [Bug-gnulib] safe-read.[ch] (safe_read): what do you think?, (continued)
- Re: [Bug-gnulib] safe-read.[ch] (safe_read): what do you think?, Paul Eggert, 2002/11/21
- Re: [Bug-gnulib] safe-read.[ch] (safe_read): what do you think?, Bruno Haible, 2002/11/21
- Re: [Bug-gnulib] safe-read.[ch] (safe_read): what do you think?, Bruno Haible, 2002/11/22
- [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?, Jim Meyering, 2002/11/23
- Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?, Bruno Haible, 2002/11/25
- Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?, Paul Eggert, 2002/11/25
- Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?, Bruno Haible, 2002/11/26
- Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?, Paul Eggert, 2002/11/30
- Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?,
Jim Meyering <=