Re: "Documentation by paper"

[Robert Dewar <dewar at gnat dot com>]

Jamie Lokier wrote:

> 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.

Yes, of course, that's what I said. The point (and the important
difference) is that this documentation extraction is not an
integral part of the language

> 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.

nor is it defined within the language

> 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.

Yes, indeed you can often deal with what might otherwise be seen
as deficiencies in a language with external tools (cf lint).

> (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).

Right, but that of course is a concious choice (the duplication).
Pascal for instance avoids that duplication. In practice there is
no inconvenience here, since changing the physical interface will
of course affect the implementation in any case.

> 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.

Well that's a point of disagreement, I see no reason for
duplicating the interface specs. of course this is also
partially dependent on tools. I am assuming that any reasonable
environment is set up so that the spec you want is a mouse click
away (that's certainly the way we edit any Ada source using GPS
or GLIDE).

> 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.

I think this duplication is a mistake. perhaps it reflects
a poor tool environment?