From owner-freebsd-current Tue Dec 9 06:33:45 1997 Return-Path: Received: (from root@localhost) by hub.freebsd.org (8.8.7/8.8.7) id GAA05440 for current-outgoing; Tue, 9 Dec 1997 06:33:45 -0800 (PST) (envelope-from owner-freebsd-current) Received: from ns1.yes.no (ns1.yes.no [195.119.24.10]) by hub.freebsd.org (8.8.7/8.8.7) with ESMTP id GAA05426 for ; Tue, 9 Dec 1997 06:33:33 -0800 (PST) (envelope-from eivind@bitbox.follo.net) Received: from bitbox.follo.net (bitbox.follo.net [194.198.43.36]) by ns1.yes.no (8.8.7/8.8.7) with ESMTP id OAA02956; Tue, 9 Dec 1997 14:33:26 GMT Received: (from eivind@localhost) by bitbox.follo.net (8.8.6/8.8.6) id PAA18426; Tue, 9 Dec 1997 15:32:49 +0100 (MET) Message-ID: <19971209153249.09488@follo.net> Date: Tue, 9 Dec 1997 15:32:49 +0100 From: Eivind Eklund To: Terry Lambert Cc: current@freebsd.org Subject: Re: VM system info References: <19971209013941.17444@follo.net> <199712090203.TAA02842@usr05.primenet.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.88e In-Reply-To: <199712090203.TAA02842@usr05.primenet.com>; from Terry Lambert on Tue, Dec 09, 1997 at 02:03:41AM +0000 Sender: owner-freebsd-current@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Tue, Dec 09, 1997 at 02:03:41AM +0000, Terry Lambert wrote: > I'm firmly in the "if you commit it, document it" camp. > > HOWEVER... > > Inline documentation is just as bad, or worse, than non-inline > documentation. > > I disagree with the premise that it "is much more likely to be kept > up-to-date". > > Further, such documentation tends to obfuscate otherwise readable code > with all sorts of non-code pieces, making it less likely the code will > be maintained, either. Here is the way I work: (1) Files should have a single short comment at the top explain what this file is for. Maximum 3 lines. (2) Functions have a brief (1-2 lines) comment giving their reason for being. (3) Variables should have comments unless they have extremely explict names. You should never have to go hunting through the code to find how a variable is used; each variable is only allowed to have a single clear purpose. (4) Code is not commented. If necessary, the function comment can contain a reference to external documentation that explain the code. This should only happen for core functionality that can't be be implemented simply; in other cases, either drop the functionality or re-implement until it is simple. If something is so complex that it needs external documentation, it had better be non-changing. (5) Code prerequisites is documented through assert() or similar functionality. (6) Data structures are documented through a full invariant. This invariant is not necessarily called from the program, but it has been used during testing and is used to check any changes to manipulation routines. These rules work amazingly well. They work especially well when coupled with reviews or inspections (as in the formal review researched by IBM), as they create a good background for an inspection, but I don't think I've ever seen them result in outdated comments (even without regular reviews). BTW: If anybody is interested, I have a couple of invariants for FreeBSD kernel data structures. I haven't committed them as they would be dead code except when somebody actively used them to debug. They are too expensive to generally enable, even when running 'DIAGNOSTIC'. (They've saved my skin a couple of times, though.) Eivind.