Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!osu-cis!dsacg1!dsacg3!vfm6066
From: vfm6066@dsacg3.UUCP (John A. Ebersold)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Summary: Comments should say WHY not WHAT.
Keywords: comments,
Message-ID: <1345@dsacg3.UUCP>
Date: 17 Feb 89 14:25:58 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM> <782@cadillac.CAD.MCC.COM>
Reply-To: vfm6066@dsacg3.UUCP (John A. Ebersold)
Organization: Defense Logistics Agency Systems Automation Center, Columbus
Lines: 44

My observations.

IMHO comments should document:

Why a particular data structure is being used. 

Why that *seemingly* silly bit of code was written.  You know, the code your
read and a say to yourself.  "This is stupid.  It doesn't need to be done
this way.  I'll change it."  GOTCHA.

Comments should documents side effect created or depended on - I know,
a bad idea but it happens.

Module comments should give the big picture.

Comments should NOT restate the syntax.

Programmer who write comments like:

/*
** See if you can figure this out.  Ha.
*/

should be condemmed to writing an operating system in BASIC without using
GOSUB.

We see the frenzied Maintainence Programmer grabbing shirt of
the perpetrator of the above comment and hear the sound of their hand
knocking sense into the errant comment writer.  Smeck, smeck, smeck,
smeck, smeck.

The right way to write a comment :-) :

I once wrote a twenty line comment to document on interrupt handler, its
expected data arrival rate, how it could be blown out of the water and why
it probably would not happen.

The interrupt handler was less than ten lines of C code.

-- 
Speaking for myself:
John A. Ebersold, Unify Corporation @ Defense System Automation Center
osu-cis!dsacg1!dsacg3!vfm6066	      Columbus, Ohio 1-614-238-5923 AV-850 5923
Systems with poorly understood requirements cannot be developed in a crunch.