"Documentation by paper"

[Robert Dewar]

Jamie Lokier wrote:

> Robert Dewar wrote:
> 
>>I would also say that it is unacceptable to start work on
>>an implementation without first creating the fully commented spec.
> 
> 
> How do you write the fully commented spec of an implementation which
> may take 10 years to figure out what it should do exactly?  You can
> easily be stuck with a spec that is not practical to implement, or
> does not behave as you hoped it would.  Sometimes the only way to
> understand the implications of the logic of a specification is to have
> an implementation to hand.

Implementing something without knowing what you are implementing
is a recipe for mess. Of course you go through a prototyping
process in which the spec can and will change. Note that the
waterfall model is largely replaced by the spiral model these
days for precisely that reason.

> To pick an example, are you saying all of the exposed mechanism of the
> VM layer of the Linux kernel must be fully specified before anyone
> begins to implement it?  That's absurdly impractical, because until
> many varying structures have been tried, nobody knows what will work
> well.  Only the highest levels of specification are possible in
> advance.

I very strongly disagree with this. You cannot implement anything
without knowing what you are implementing. The rule is quite simple
write down what you are going to implement before you implement it.
If during implementation you find problems in the spec, then you
modify the spec, but once you get into this discipline it is
surprising how little such modification is needed.

For PD/FMS, an operating system I wrote for Honeywell (included
visual interface, full development tools, multi tasking exec,
debugger, fancy file system with indexed files, database
manager and lots of other goodies), the reference manual was
completely written before a line of code was written, and
relatively few changes were made to that manual later on.

Yes, with some projects it is hard to specify so much in
advance, and that is why you must iterate. But when you
start to write a C function, you must have some idea of
what you are doing, the rule is simply, please write it
down first. Documenting after the fact is a recipe for
poor and inadequate documentation.

But probably this has got off topic, the important thing
which everyone should agree on is that at least when code
is delivered for integration, it should have full functional
specs, and that should be a prerequisite for inclusion.
Furthermore, a mere reference to a paper with an algorithm
is NOT adequate documentation.

> This is what I meant by non-waterfall development style: sometimes
> it's just _easier_ to develop an implementation and the details of its
> spec at the same time (and change all the callers as you go if there
> are any by then), because it's too hard to figure out what is
> practical to implement until you have done some of it.

The spiral model is well suited to dealing with this kind
of situation.

> However you may have a point.  Some parts of GCC are an example of
> this type of development gone awry :)

Indeed :-)