In some email I received from xs@kittenz.org, sie wrote:
> on Sun, Jun 16, 2002 at 03:18:06PM -0400, Bill Sommerfeld wrote:
> > > - statement about which locks are expected to be held and how.
> > > - statement about which interrupts are expected to be masked or not.
> > > - statement about what the function does, including what is considered
> > 
> > So, it's worth noting that 2/3 of these are things which can
> > conceivably be checked automatically.  One way to do this is with
> > run-time asserts of various forms.
> > 
> > Block comments saying "lock XXX must be held" are likely to rot over
> > time (i.e., get out of synch with reality).  Assertions, on the other
> > hand, will be tripped over if the code is used..
> 
> I noticed LOCK_ASSERT({!,}simple_lock_held()) in several places. Would this
> suffice for statement #1?
> Does the comment block above sys_setpgid() in sys/kern/kern_prot.c satisfy #3?

Checks in the code does not replace the need for comments.

IMHO, They're at opposite ends of the spectrum of code development.
Well, maybe not quite so extreme...but code checks are there to catch
problems when you've written your code and have begun testing, comments
are there to help you write your initial code.

In order to use some arbitrary function, I should not need to read code
itself (comments not being code).

Darren