Re: public headers
On Sep 26, 2:20 pm, "ie...@free.fr" <ie...@free.fr> wrote:
You really should not confuse the header files with the documentation of
the API, they should be separate, even if it is just by generating the
documentation from the source via doxygen or similar tools. Neither C
not C++ is expressive enough to accurately describe an interface (such
as pre- and post-conditions, invariants, etc.) with just the the
information usually found in a header file.
Why not ? It's possible to describe a library with the headers. When
the developer make his library, he puts the information for the use in
comment of the header file.
I come from a language where looking the header files teach you
everything you need to use standard libraries.
That's completely false, since it's not true for any language.
Headers are meant for the compiler, documentation for human
readers, and the two readers have a different set of constraints
and expectations.
In a good organization, typically, you're write the
documentation first, then generate (part of) the headers from
it. Failing this (and far more common), you'll write the
documentation in the form of (extractable) comments, then add
whatever extra stuff the compiler requires; the documentation
tool then extracts and formats the original comments. This is
possible in both C and C++; C++ allows considerably more
options, however, with regards to how to do it.
The classical C idiom which you showed, for example, requires
all objects to be allocated dynamically, and for the user to
explicitly free them; in C++, the compilation firewall idiom
does the same thing, except that the object can easily be made
to act like a pure value type, which manages the lifetime of the
actual implementation data itself. And if performance
considerations mean that the dynamic allocation has to go, then
in C++, you can at least declare the data elements private,
where as in C, there's no way you can prevent client code from
depending on them.
--
James Kanze (GABI Software) email:james.kanze@gmail.com
Conseils en informatique orient=E9e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S=E9mard, 78210 St.-Cyr-l'=C9cole, France, +33 (0)1 30 23 00 34