Re: "Documentation by paper"

[Jamie Lokier <jamie at shareable dot org>]

Robert Dewar wrote:
> >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).

As long as it doesn't interrupt the editing flow, e.g. by hiding the
code I'm working on.

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

Yes it does, but it also reflects two different needs from the documentation:

    1. Callers of a function need to see documentation and minimal
       type signatures.  For this, header files are quite good, as are
       popup documentation, "mouse click" etc.

    2. Implementers of a function which is not necessarily written in
       "waterfall" style, i.e. not spec first, need to see and edit
       documentation at the same time as the corresponding code.

The best language environment I've used for handling code with
documentation is Emacs Lisp, where a couple of keypresses brings up
the documentation for any function without interrupting the flow of
editing.  Rather than jumping to the other text, it pops up occupying
part of the screen.  If Emacs did that for other languagues such as C,
it would be exceptionally useful; it is perfect for the caller
audience.

Emacs Lisp also requires that you write interface and specifications
right inside the code which implements them.  This works very well,
and not just for me.  Look at the libraries of 3rd party Emacs Lisp
code: authors tend to document every public function instinctively.

In theory Java is similar, but the barrier to using the Javadoc
comments is higher than in Emacs Lisp, and I found myself writing Java
code without extensively documenting functions using Javadoc.  Java
code from other authors that I have worked with is similar, although I
know that any professional quality library should have Javadoc comments.

An interesting difference.  I'm sure this has a lot to do with tools,
and with the fact that Emacs Lisp comments use simple conventions
(like GNU standard comments: capitals indicate parameter names, short
flowing descriptions), whereas Javadoc requires more skilled use of
markup and is not as plain to read for the person editing the source code.

That last point may be relevant to the style of comments preferred in
GCC source...

-- Jamie