Re: Proposal for automatic generation of c++ header files

[Achilleas Margaritis <axilmar at gmail dot com>]

On Fri, Jan 14, 2011 at 3:35 PM, Robert Dewar <dewar@adacore.com> wrote:
> Ian Lance Taylor <iant@google.com> wrote:
>
>> In C++, I personally spend very little time doing what I would describe
>> as "maintaining headers." ?I write class definitions in .h files and
>> function implementations in .cc files. ?The only data which appears in
>> both places is the function signature. ?Yes, it would be slightly nice
>> if I didn't have to write that twice. ?But it's a minor issue.
>
> Interesting, as an Ada person, I actually LIKE the idea of writing the
> signature in both places. The Ada view here is that it serves very
> different purposes, in the header, it is part of the specification,
> and in the implementation it is there for easy access to anyone
> reading the implementation, and is a reminder that the implementation
> must conform to this spec. I think it helps readability to have it in
> both places (with of course the compiler checking that it is the same).
>
> Its a slight pain for the writer, but in Ada we never care even a little
> bit about the convenience of the writer over the convenience of the
> reader, and of course appropriate tools could simplify the duplication.
>
>> Don't you ever had to modify the classes after you've written them? I
>> am surprised, because I have talked to other developers and they have
>> too said that it would be nice if headers could be avoided.
>
> Again, I like using headers in this way, I think it clarifies the
> structure of the program. As I say, I am influenced by Ada. It is
> always interesting to see the range of possible views of C headers
> from
>
> a) annoying junk required by the compiler, spend the least possible
> time messing with them, and certainly don't bother commenting them.
>
> to
>
> b) headers function like package specifications in Ada, and should
> be regarded as specifications and fully commented accordingly.
>
> If you follow path b) you end up with C or C++ code that has quite
> an Ada-like feel with regard to separation of spec and implementation.
>

I've heard this argument in other places that headers serve as
specification, aiding in readability and conformance. I strongly
disagree, for the following reasons:

1) conformance is checked by the compiler.  There is no need for the
programmer to check the conformance of the implementation to the
specification. If it compiles without errors, the implementation is
ok.

2) the actual knowledge about the program stored in a header is, from
my rough estimation, up around 20% of what the program actually does.
In order to incorporate the actual knowledge required, a lot of
documentation has to be written. I comment my code with docified
comments heavily in order to document every little detail of my
program. This knowledge can never be deduced by the headers. The
docified comments result in a nicely formatted documentation which is
actually much easier to read than code in headers.

So, if the compiler checks the code, and the documentation says
whatever must be said about the program, headers are completely
redundant.