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

[Bruno Haible]

Hi Jim,

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.
(In C++ the size ratio between .h to .c is around 1:3, in C it may be
something like 1:5 or 1:10.)

So if you don't want two copies of the function specification, keep
the one in the .h and rip out the one in the .c.

This is also based on the respective frequency of these development
actions:
  1) [Frequent] Read the specification of a function.
  2) [Less frequent] Read or update the implementation of the
     function.
  3) [Rare] Change the specification of a function.

>From this perspective, you can see that ripping out the comment of the
.c file will make operation 2 harder, but operation 3 easier. But oh
well, if you like that, go for it. Keep the specification in the .h file.

Karl Berry writes:
> It's painful enough to have to keep the list of
> functions (especially with prototypes) in sync.

Come on, for a function part of gnulib the prototype changes once in
10 years!

Bruno