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,LOTS_OF_MONEY,
	MSGID_RANDY autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,e61c8636ef35379d
X-Google-Attributes: gid103376,public
X-Google-ArrivalTime: 2001-01-19 11:10:08 PST
Path: 
 supernews.google.com!sn-xit-02!sn-xit-04!supernews.com!xfer13.netnews.com!netnews.com!cpk-news-hub1.bbnplanet.com!news.gtei.net!nntp2.deja.com!nnrp1.deja.com!not-for-mail
From: mark_lundquist@my-deja.com
Newsgroups: comp.lang.ada
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings
Date: Fri, 19 Jan 2001 18:55:53 GMT
Organization: Deja.com
Message-ID: <94a2jj$tc2$1@nnrp1.deja.com>
References: <93objj$guk$1@nnrp1.deja.com>
 <ZSS76.120778$A06.3893142@news1.frmt1.sfba.home.com>
 <93q77h$rr6$1@nnrp1.deja.com> <940f9j$nj2$1@nnrp1.deja.com>
 <94299p$8dd$1@nnrp1.deja.com>
 <J_e96.5326$DI.58950@e420r-atl1.usenetserver.com>
NNTP-Posting-Host: 130.213.204.212
X-Article-Creation-Date: Fri Jan 19 18:55:53 2001 GMT
X-Http-User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt)
X-Http-Proxy: 1.1 x61.deja.com:80 (Squid/1.1.22) for client 130.213.204.212
X-MyDeja-Info: XMYDJUIDmark_lundquist
Xref: supernews.google.com comp.lang.ada:4219
Date: 2001-01-19T18:55:53+00:00
List-Id: <comp.lang.ada>

In article <J_e96.5326$DI.58950@e420r-atl1.usenetserver.com>,
  "Peter Richtmyer" <pmr@efortress.com> wrote:
> <mark_lundquist@my-deja.com> wrote in message
> news:94299p$8dd$1@nnrp1.deja.com...
> > In article <940f9j$nj2$1@nnrp1.deja.com>,
> >   peter_richtmyer@my-deja.com wrote:
> > > [...]
> > > Putting examples in documents is
> > > somewhat similar to putting comments in code. It
> > > is not necessary, but it sure makes it easier for
> > > the readers.
> >
> > Of course you don't mean that comments are unnecessary in program
text,
> > only that they do not affect the function :-)
> >
> Actually, I did mean they are *unnecessary*, meaning *not needed*.
>
> They are certainly not required by the compiler. With respect to the
human
> reader,
> given enough time, and given access to the requirements, design
specs, PDl,
> interface
> specs,  other docs, other people, etc,  the program comments are *not
> needed*.

So strictly speaking, it's not comments that are necessary (for
understandability), but documentation...

I almost said that in another post, but I didn't want to cloud the
issue!  Bad call, I guess... :-)

I think the idea of embedded hyperlinks in comments to navigate out to
supporting documentation of the kind you mention could really be
worthwhile (DING!  Cue for Bob-Leif-XML-followup :-) :-) :-)

>
> Peter
>
> P.S.  Why do I keep using * instead of "  ?     :-)
>

Maybe some kind of pinky finger deformity? :-)

Cheers,
Mark


Sent via Deja.com
http://www.deja.com/