On 1/14/2011 8:47 AM, Achilleas Margaritis wrote:
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.
The task of documenting specifications (what needs to be known by clients) is radically different from documenting implementations (what needs to be known by people fiddling with the implementation, the client should NEVER need to look at the implementation, and implementation details are not only irrelevant to the client, but it is evil for the client to depend on them). That's the Ada philosophy in a nutshell, for Ada people, it is the single most important feature of the language that it encourages and to some extent mandates separation of spec and implementation (I say to some extent, because I have seen C folk writing Ada who regard the Ada specs as nuisance headers and don't document them at all, which is a horrible sin from an Ada perspective).
So, if the compiler checks the code, and the documentation says whatever must be said about the program, headers are completely redundant.
But then you don't have proper documentation of the specification.
