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,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-20 06:30:10 PST
Path: 
 supernews.google.com!sn-xit-02!supernews.com!isdnet!news-spur1.maxwell.syr.edu!news.maxwell.syr.edu!nntp2.deja.com!nnrp1.deja.com!not-for-mail
From: Robert Dewar <robert_dewar@my-deja.com>
Newsgroups: comp.lang.ada
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings
Date: Sat, 20 Jan 2001 14:24:50 GMT
Organization: Deja.com
Message-ID: <94c73f$hs9$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>
 <94a2jj$tc2$1@nnrp1.deja.com>
NNTP-Posting-Host: 205.232.38.14
X-Article-Creation-Date: Sat Jan 20 14:24:50 2001 GMT
X-Http-User-Agent: Mozilla/4.61 [en] (OS/2; U)
X-Http-Proxy: 1.0 x70.deja.com:80 (Squid/1.1.22) for client 205.232.38.14
X-MyDeja-Info: XMYDJUIDrobert_dewar
Xref: supernews.google.com comp.lang.ada:4232
Date: 2001-01-20T14:24:50+00:00
List-Id: <comp.lang.ada>

In article <94a2jj$tc2$1@nnrp1.deja.com>,
  mark_lundquist@my-deja.com wrote:
> 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 :-) :-) :-)

Generally I much prefer ALL technical documentation (as opposed
to user documentation) of the code to be in the code. Why?
Simple, in my experience VERY few programmers have the
discipline to maintain external documents, so they quickly get
out of sync and become completely useless.

It is hard enough for most people to be diligent about
maintaining comments and documentation that *are* part of
the source code.

You really have to develop the exact opposite opinion from
"comments don't really matter and have no effect", and consider
that a bad spelling in a comment is a real bug :-) Sure a bad
spelling is not serious, but the attitude that will not
tolerate bad spelling in program comments is one that goes
along with a commitment to maintaining good internal
documentation.


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