"Documentation by paper"

[Robert Dewar]

> Robert, the Ada interface description is far from a spec, for any
> nontrivial function.  Almost any real spec will describe restrictions
> on input, and guarantees about the output, that are not written
> in a form that the compiler parses (even in languages like Eiffel with
> support for preconditions and postconditions).  This means that we
> are back to comments.

Of course, but the interface description is required to be there, and it is
universal Ada practice to put the necessary additional comments in the spec.
In C, header files are not required, and although it *might* be universal
practice to create header files analogous to Ada specs, in practice it is
not. Certainly in Ada you can't go creating a package body before you
have created the package spec, and no one would think of trying :-)

By the way, for me, even for a trivial function, comments are essential. I
very much dislike the style of depending on names of parameters etc and
having the reader guess the function. To me, comments must be complete
and describe all parameters etc in detail, without depending on any
guesswork. I would also say that it is unacceptable to start work on
an implementation without first creating the fully commented spec.