From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=0.7 required=5.0 tests=BAYES_00,INVALID_DATE,
	REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,1ff5003422436e4
X-Google-Attributes: gid103376,public
X-Google-ArrivalTime: 1994-10-12 08:50:35 PST
Path: 
 bga.com!news.sprintlink.net!deathstar.cris.com!news1.oakland.edu!vtc.tacom.army.mil!ulowell!europa.eng.gtefsd.com!swiss.ans.net!newsgate.watson.ibm.com!watnews.watson.ibm.com!ncohen
From: ncohen@watson.ibm.com (Norman H. Cohen)
Newsgroups: comp.lang.ada
Subject: Re: Easily-Read C++?
Date: 12 Oct 1994 13:15:36 GMT
Organization: IBM T.J. Watson Research Center
Distribution: world
Message-ID: <37gnho$nbt@watnews1.watson.ibm.com>
References: <941005030023_73672.2025_DHR103-1@CompuServe.COM>
   <Cx7o3H.3pp@uunet!aadt> <36v7p4$amf@gnat.cs.nyu.edu>
   <36v90m$9r4@cmcl2.NYU.EDU> <124377@cup.portal.com>
 <37emcj$sk5@gnat.cs.nyu.edu>
Reply-To: ncohen@watson.ibm.com
NNTP-Posting-Host: rios8.watson.ibm.com
Date: 1994-10-12T13:15:36+00:00
List-Id: <comp.lang.ada>

In article <37emcj$sk5@gnat.cs.nyu.edu>, dewar@cs.nyu.edu (Robert Dewar)
writes: 

|> There are to my mind three justifications for comments: 
|>
|> Saying WHY you are doing something, and WHY you did it that way
|>
|> Saying WHY you did NOT do something, and WHY you did NOT
|>
|> Describing WHAT the code does, but at a higher level of abstraction
|> than the code itself.

Another purpose is to leave advice to future maintainers about how to
add enhancements that you have anticipated: 

   -- Additional devices can be accommodated by deriving new
   --   types from Driver_Type.

   -- To add a reserved word, simply add it to the aggregate used to
   --    initialize Vocabulary.  Add the new word in alphabetical
   --    order so that the binary search in Lookup will continue to work.

In modifying other peoples' code, I've sometimes found comments
performing another useful function as well:  Utterly incoherent comments
warn the reader that the original programmer had no idea what the
*(^%(*$)%!! he was doing, so that the reader knows to regard the code
with suspicion.

My favorite comment (for honesty, if nothing else) comes from a ksh
profile: 

   #the next two lines are copied from the korn shell paper
   #i don't know why it works, but it seems to

The runner up comes from an assembly-language program: 

   xor R3,R4,R3    THIS IS TRICKY.

--
Norman H. Cohen    ncohen@watson.ibm.com