Re: netlink tester program

["John S. Denker" <jsd@monmouth.com>]

On 06/02/2003 05:56 PM, David S. Miller wrote:
 >>
 >> I always have to wonder about someone who can't live with just
 >> working code to study, and absolutely requires some document
 >> describing it.
 >>
 >> What is better or more accurate description than code itself!?!?!

I am very grateful for the kindness of those who
have written the code in question and made it
available to help others.  I wish to repay that
with help and kindness, not the opposite.  Today
I can help by speaking the truth, and the truth
is that documentation is sorely needed.

There's no point in writing code if few people
use it.  Linux is hanging in there at a few
percent market share.  That's not going to grow
unless there is better documentation.


On 06/02/2003 09:56 PM, David Brownell replied:
 >
 > Well, the difference between code and its spec is
 > generally a bug that needs to be fixed ... which
 > can be in the code as well as in the spec.  And for
 > reasonable design specs, it's more likely in the code.
 >
 > But if there's only the code, it gets a lot more
 > troublesome when things don't behave "as expected".
 >
 > People who are in a position to change the code
 > to meet their expectations may not care, but that's
 > rarely a significant chunk of the user community.
 >
 > And in particular, writing tests against the code
 > is generally the wrong way to go.  They need to be
 > written against some kind of spec.

I have to agree with Mr. Brownell on this one.


 >> What is better or more accurate description than code itself!?!?!

There are two ideas mixed up there.
  -- Better documentation.
  -- Accurate description.

1) Yes, code is the most accurate description of the code.
But it is not to be confused with good documentation.

2) Documentation should be clear and concise.
Code must attend to all the details.

3) Sometimes efficiency requires that the code be
tricky.  Documentation must not be tricky.

4) In theory, very well-commented code might
approximate its own documentation.  But I haven't
seen any such code lately.  Here are _all_ the
comments from xfrm_input.c, a 454-line file:

/* Fetch spi and seq frpm ipsec header */
         /* Allocate new secpath or COW existing one. */
/* Fetch spi and seq frpm ipsec header */
                 iph = skb->nh.ipv6h; /* ??? */
                 if (x->props.mode) { /* XXX */
         /* Allocate new secpath or COW existing one. */
#endif /* CONFIG_IPV6 || CONFIG_IPV6_MODULE */


If you were teaching a programming course, how would
you grade an assignment turned in with that level of
commenting?

5) In the engine of a piston-driven airplane, there
are two spark plugs in every cylinder.  Obviously
that costs twice as much and weighs twice as much
as having only one.  But the redundancy makes the
system thousands of times more reliable.

Similarly, writing code _and_ documetation is about
twice as expensive as writing the code alone.  But
the redundancy makes it possible to achieve much
greater reliability.  Also maintainability and
extensibility.

6) Adding extra vehemence '!?!?!' does not add
clarity to the discussion.

*) et cetera.