Date: Tue, 9 Dec 1997 15:32:49 +0100 From: Eivind Eklund <perhaps@yes.no> To: Terry Lambert <tlambert@primenet.com> Cc: current@freebsd.org Subject: Re: VM system info Message-ID: <19971209153249.09488@follo.net> In-Reply-To: <199712090203.TAA02842@usr05.primenet.com>; from Terry Lambert on Tue, Dec 09, 1997 at 02:03:41AM %2B0000 References: <19971209013941.17444@follo.net> <199712090203.TAA02842@usr05.primenet.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19971209153249.09488>