Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Jacob Sparre Andersen <sparre@nbi.dk>]

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