Robert Dewar wrote:
Now in the case of Java, there is no natural separation of specs and
implementation (for those of us of the Ada persuasion, this is one
of the serious deficiencies of the language). So you are most definitely
forced to use the approach of documentation extraction (assuming for
a moment that we are all agreeing on the merits of having the *source*
of the documentation reside with the source files).
That _is_ the natural separation of specs and implementation in Java:
the class source is the implementation (which you might not have
access to), and the extracted documentation is the spec.
The mechanics of this can be seen as a way to synchronise text and
declarations between the implementation and spec. The fact that
everyone does it in the direction class -> documentation is
conventional, it's not a given.
In principle you could edit text in the spec (i.e. the documentation)
and have changes applied automatically to the class source, but I've
not heard of any editing environments that work that way.
(Ada and C imply _some_ duplication between the spec and
implementation, don't they? Every C type signature in a header file
is repeated in the implementation; it's accepted practice that you
have to edit both places to keep them synchronised).
I far prefer the fully documented header approach when it comes to C,
I like full documented headers a lot. The problem I find is what to
put in the implementation file? When editing something in a .c file,
it's very helpful to have the textual comments which describe the
interface near the source which implements them, usually as a comment
just prior to the function it documents.
In my own programs, I tend to duplicate interface comments and whole
file explanations: what's in the header file is repeated in the
implementation file. I hate the duplication, and the extra work
required to maintain it, but find it makes the source that much
clearer than a bunch of functions with no interface comments would be.
A tool which keeps the two synchronised might be helpful, but I
haven't seen one or thought much about that.
-- Jamie