Subject: Re: Adding to KNF.
To: Darren Reed <darrenr@reed.wattle.id.au>
From: John F. Woods <jfw@jfwhome.funhouse.com>
List: tech-kern
Date: 06/17/2002 11:26:19
> Checks in the code does not replace the need for comments.

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

If the checks are at the beginning of a function, and laid out clearly and
with consistent style, they can mostly serve the commentary purpose fairly
well -- except, of course, if you're reading automatically-extracted 
documentation which is separate from the code.

Unfortunately, the absence of such checks in a function can't be taken to
mean that a function has no requirements, whereas a standardized comment of
"Locks: none" can.

I've written code for several heavily-multithreaded and heavily-multiprocessor
applications and systems.  Automated checks are extremely useful for 
identifying bugs before they bite; but proper and consistent comments
are extremely useful for not writing the bugs in the first place.  The
thirty seconds it will cost a developer to enter such a comment could save
someone else hours of debugging time.

(By the way, for automated lock checking, automatic lock hierarchy validation
can be a real timesaver.)