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-Thread: 103376,81054609038e88e3
X-Google-Attributes: gid103376,public
X-Google-Language: ENGLISH,ASCII-7-bit
Path: 
 g2news1.google.com!news1.google.com!newsfeed.stanford.edu!newsmi-us.news.garr.it!newsmi-eu.news.garr.it!NewsITBone-GARR!newsserver.cilea.it!news.crs4.it!not-for-mail
From: Jacob Sparre Andersen <sparre@nbi.dk>
Newsgroups: comp.lang.ada
Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse
Date: 18 Oct 2004 10:17:21 +0200
Organization: CRS4, Center for Adv. Studies,
 Research and Development in Sardinia
Message-ID: <rlsacuke8z2.fsf@jacob.crs4.it>
References: <2sqmccF1oit5sU1@uni-berlin.de> <uwtxz3dfd.fsf@act-europe.fr>
 <2sr4jaF1od20uU1@uni-berlin.de> <ur7o63lmp.fsf@obry.org>
 <mailman.253.1097407620.390.comp.lang.ada@ada-france.org>
NNTP-Posting-Host: jacob.crs4.it
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: pietro.crs4.it 1098082461 22955 156.148.71.80 (18 Oct 2004 06:54:21
 GMT)
X-Complaints-To: news@nntpserver.crs4.it.
NNTP-Posting-Date: 18 Oct 2004 06:54:21 GMT
User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2
Xref: g2news1.google.com comp.lang.ada:5390
Date: 2004-10-18T06:54:21+00:00
List-Id: <comp.lang.ada>

Marius Amado Alves wrote:

> I appreciate the requirement for some kind of master system
> containing both documentation and program elements.
> 
> The original Knuthian literate programming idea was not special
> comments in the source code but the other way around, source code
> fragments embedded in the text, which text being a piece of
> technical literature describing the system under construction.

Nice idea, but hard on the compiler, if you develop like I do (plenty
of compiles just to check the state of things and what's next on the
to-do list).

> It's not just a difference of perspective.
> 
> Documentation and source code are two very different things, and one
> should not step on the feet of the other.

Agreed.

> Overloading the source code with documentation elements ruins the
> source code.
> 
> Lately I've been putting all comments, if any, in the bottom of the
> source code file.

Why at the bottom and not at the top?

> And of course one should always write code in a way that it reduces
> the need for comments.

Aye!

> When some unit needs extensive commentary, the place for that is in
> a separate file.

Yes.  But I still think that putting a few words about the purpose of
a file in its beginning is a good practice.

> The link between documentation and source code items is based on the
> names of the source code entities.

Aye!

Jacob (who feels like he might as well have an AOL address ;-)
-- 
"Three can keep a secret if two of them are dead."