In some email I received from David Laight, sie wrote:
> > 
> > One of my pet hates is the lack of documentation with much of the code,
> > ie. comments.  As we move forward, more and more code gets written and
> > it doesn't get any easier to understand how it works.  At present we
> > are without much in the way of SMP support but once that is added, the
> > code will become even more complex, over time.
> > 
> > What I'd like to suggest is that in going forward, we adopt some changes
> > to the KNF that require people to at least put more text in a comment
> > block prior to the function.
> 
> I hate mandatory comment blocks before functions!

Right, well you could have stopped there then because the rest of
your comments fed back into this single line.

> They tend to end up telling you stuff that can be figured out
> immediately - rather than stuff that is slightly obscure.

There is nothing wrong with pointing out the obvious.  At least it
makes it explicitly clear that the obvious interpretation is correct.

How do you audit a function for correct functionality if there is no
statement about what it is meant to do ?

This is actually the crux of what I'm on about here.  I'm seeing too
much "new" code written that has little or no explanation about what
it is meant to be doing to feel comfortable about it doing the right
thing.  There is no way you can convince me that a function is "correct"
as a result of an "audit" if there is no comment block stating what it
does (or is meant to do).

> > Some things which I think would be or are going to be useful:
> > 
> > - statement about which locks are expected to be held and how.
> >   this should include extra comments if a lock is acquired or released
> >   prior to returning.
> 
> It is MUCH more important to add comments to structure definitions
> indicating what the fields are for, and which lock covers each
> field.  Then you can CHECK whether the routine is doing the right thing.

That's good for locks that protect individual fields within a structure,
but what about locks for tables, etc ?

> Comment blocks (esp. those above functions) get out of date very
> easily.

Well, that is another problem altogether.  People updating code should
also be updating comments, as appropriate.  Software development is not
just about cutting code.  Bugs introduced in comments are just as henious
as bugs introduced in code.

Darren