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=-1.9 required=5.0 tests=BAYES_00 autolearn=ham
	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 11:08:18 PST
Path: 
 supernews.google.com!sn-xit-02!supernews.com!news.gv.tsc.tdk.com!newsfeed.berkeley.edu!ucberkeley!hammer.uoregon.edu!skates!not-for-mail
From: Stephen Leake <stephen.a.leake.1@gsfc.nasa.gov>
Newsgroups: comp.lang.ada
Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings
Date: 20 Jan 2001 14:02:48 -0500
Organization: NASA Goddard Space Flight Center
Message-ID: <uwvbq11yf.fsf@gsfc.nasa.gov>
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> <94c73f$hs9$1@nnrp1.deja.com>
NNTP-Posting-Host: anarres.gsfc.nasa.gov
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: skates.gsfc.nasa.gov 980018138 5157 128.183.220.71 (20 Jan 2001
 19:15:38 GMT)
X-Complaints-To: dscoggin@cne-odin.gsfc.nasa.gov
NNTP-Posting-Date: 20 Jan 2001 19:15:38 GMT
User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.6
Xref: supernews.google.com comp.lang.ada:4240
Date: 2001-01-20T19:15:38+00:00
List-Id: <comp.lang.ada>

Robert Dewar <robert_dewar@my-deja.com> writes:

> 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.

In general, I agree. But there are times when an external document is
better:

1) The document presents an overview of the design of a large system,
   so it uses diagrams, and it doesn't belong in any one source file.

2) The document presents an algorithm that is best described by
   mathematical notation; flat ASCII is just not good enough for this.

I'm sure there are other times, but these are the ones I've run
across.

When I write an algorithm document, I define the mapping from math
symbols to Ada names. I also use LaTeX, so I can edit the document in
the same editor (Emacs) as the Ada source; that makes it much easier
to keep them in synch.

-- 
-- Stephe