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.2 required=5.0 tests=BAYES_00,INVALID_MSGID,
	REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 11390f,4c42ac518eba0bbe
X-Google-Attributes: gid11390f,public
X-Google-Thread: 103376,4c42ac518eba0bbe
X-Google-Attributes: gid103376,public
X-Google-Thread: 1014db,4c42ac518eba0bbe
X-Google-Attributes: gid1014db,public
X-Google-Thread: 109fba,4c42ac518eba0bbe
X-Google-Attributes: gid109fba,public
From: "Shmuel (Seymour J.) Metz" <nospam@gsg.eds.com>
Subject: Re: Programming language vote - results
Date: 1997/10/29
Message-ID: <3457DFB4.4DCC@gsg.eds.com>#1/1
X-Deja-AN: 286745306
References: <343fbb5a.0@news.iprolink.ch> <343FD05C.8986A557@flash.net>
 <34428914.2D71D0F@ibm.net> <01bcd87f$7fefcf00$25a43a91@basil.omroep.nl>
 <34458CE3.507C@dynamite.com.au> <3444BFC6.794BDF32@druid.net>
 <34466EB4.3381@dynamite.com.au> <6275dt$agm$3@news.on>
 <344BCED0.2D51@dynamite.com.au> <62idmb$htg$1@news.on>
 <344DEAA9.5115@hal-pc.org> <01bce1bf$5c2baaa0$95b66bcf@dkelly.ark.com>
 <345776DD.424B@hal-pc.org>
Organization: EDS MS
Reply-To: nospam@gsg.eds.com
Newsgroups: comp.lang.ada,comp.lang.apl,comp.lang.c,comp.lang.c++
Date: 1997-10-29T00:00:00+00:00
List-Id: <comp.lang.ada>


Don Guinn wrote:
> 
> As far as documenting code.  Documentation is wonderful when it adds
> information and insight on what the program does.  I have seen too many
> programs full of documentation which does nothing but repeat what is
> already stated in the code itself.  It's as if the person who wrote it
> can't read his own code.

When I was drafted into teaching a programming course I told my students
that I would take points off for any comments that didn't clarify the
program and for any code that I couldn't understand. I'm older and wiser
now; if I have to teach another course I will also insist that a
randomly selected student be able to understand the code.
 
> Documentation needs to explain the concepts used in an application.  It
> should provide definitions of terms (variables) and possible things to
> watch out for.  But it should not have to translate the source code into
> English.  It should not be measured by the pound.

Amen!

-- 

                        Shmuel (Seymour J.) Metz
                        Senior Software SE

The values in from and reply-to are for the benefit of spammers:
reply to domain eds.com, user msustys1.smetz or to domain gsg.eds.com,
user smetz. Do not reply to spamtrap@library.lspace.org