Re: [tlug] linux@example.com How many widely can we do that?

[Curt Sampson <cjs@example.com>]

On 2009-10-28 13:13 +0900 (Wed), Stephen J. Turnbull wrote:

> Curt Sampson writes:
> 
>  > > Usually documented by an automatic tool that turns .h files
>  > > into prose.  (I kid you not.)
>  > 
>  > Well, it's a step above separate documentation that never gets updated.
> 
> No, it's not -- in many cases the .h is easier to read (assuming you
> can program in C, which almost goes without saying in this context).

Oh, well if that's the case, they ought just to declare the .h files the
documentation.

> But in most cases the separate documentation at least contains a
> theory of operation section, and *omits internal interfaces*.

Sure, but I'd rather have current documentation with internal references
than out-of-date documentation without. The theory of operation is a
more open question, of course, since those don't tend to bitrot so
quickly.

>  > Documentation should come from code whenever possible.
> 
> I disagree.  The code should be written to implement the documentation.

Generally that's not entirely possible. If it were, we'd just compile
and run the specification and be done with it. Which is sort of what I
was aiming at, there.

I suspect even you would prefer to put a BNF into a parser generator
than attempt to write a C program that does what the BNF specifies.

> It's good to combine the source of the spec document with the code
> as long as you're very disciplined about writing the spec and then
> changing it only in a planned way, then filling in the details in
> code.

I think it's really the other way around; when you keep them together
it takes less discipline to make sure that the spec changes when the code
changes. Otherwiswe I find people tend to fix bugs in the spec, but only
in the code, and leave the spec broken.

> But what's really bad about it is that if changing the .h
> automatically updates the documentation, the developer of client code
> is completely hung out to dry.  There is nothing left that can be
> considered an independent specification of the behavior.

Right, which is a good thing, IMHO. Code is, de facto, a specification.
If you have an independent specification, now you have two
specifications, which is very much like having two clocks.

> Even backward compatibility can be immediately disposed of as "we
> changed unspecified behavior, you really shouldn't be depending on
> that!" because *everything* is unspecified.

Well, only if you refuse to admit that your code is also a spec.

cjs
-- 
Curt Sampson       <cjs@example.com>        +81 90 7737 2974
           Functional programming in all senses of the word:
                   http://www.starling-software.com