Bill Sommerfeld  <sommerfeld@netbsd.org> 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..
>
>The splassert() primitive mentioned earlier is a very good idea; we
>should adopt it.
>
>				- Bill
>

In some sense locks and spl are part of a more general problem: who
can access protected resources and when.  SMP moves this line.

I certainly like the notion of an splassert() and by extension something
that can assert lock status.

There still remains the question of comments and KNF and more.

It seems to me that the primary purpose of comments is to allow the
code to be maintained.  If the code is open-sourced, it seems that the
comments should be tailored to the person chasing a bug -- not
necessarily the maintainer -- and should help to determine the overall
context of the code.  The details within this context are probably
best explained by the code itself.

At minimum it would seem that at the _file_ level, you could reasonably
expect to say what function the file encapsulates.  For example,
a device driver might announce what devices or device protocols it
is attempting to support.  The lack of such a comment has always
seemed to me to be an unwarranted display of developer hubris.