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.8 required=5.0 tests=BAYES_00,INVALID_DATE
	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-13 15:50:04 PST
Path: 
 bga.com!news.sprintlink.net!howland.reston.ans.net!gatech!swrinde!elroy.jpl.nasa.gov!netline-fddi.jpl.nasa.gov!nntp-server.caltech.edu!news.cerf.net!noc.cerf.net!nic.cerf.net!readingj
From: readingj@nic.cerf.net (John D. Reading)
Newsgroups: comp.lang.ada
Subject: Re: Easily-Read C++?
Date: 13 Oct 1994 19:33:44 GMT
Organization: CERFnet Dial n' CERF Customer
Distribution: world
Message-ID: <37k22o$mel@noc.cerf.net>
References: <941005030023_73672.2025_DHR103-1@CompuServe.COM>
 <124377@cup.portal.com> <37emcj$sk5@gnat.cs.nyu.edu>
 <37gnho$nbt@watnews1.watson.ibm.com>
NNTP-Posting-Host: nic.cerf.net
Date: 1994-10-13T19:33:44+00:00
List-Id: <comp.lang.ada>

In article <37gnho$nbt@watnews1.watson.ibm.com> ncohen@watson.ibm.com writes:
>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

I am certainly liable to be flamed for wasting bandwidth, but one of
my favorite comments was one I penned myself.  After spending some
unreasonable amount of time to get a very convoluted line of LISP
code working I added the comment:

;; That's what I like about LISP - it's self documenting

Those were my innocent pre-Net days; I didn't know about smileys.

But to bring this back to the topic under discussion, in my experience
(which includes a lot of LISP, FORTRAN, and C, and a little Ada),
there are no "easily read" languages.  There is no substitute for
learning the language.  Comments, however, are always useful for
giving a more global view of *why* something was done the way it
was.  Perhaps it is worth adding that the above *bad* comment was
involved in the code for a compiler for a proprietary language
which was supposed to be perfectly readable.  Those unfamiliar
with tha language discovered they could read a program and
understand the sequence of steps it represented without being
able to tell why they were done.  Some well-written comments were
still necessary to add that understanding.

John Reading
readingj@cerf.net