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.3 required=5.0 tests=BAYES_00,INVALID_MSGID
	autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,f34f1a1939dc0c40
X-Google-Attributes: gid103376,public
From: Robert A Duff <bobduff@world.std.com>
Subject: Re: conditional compilation
Date: 2000/08/03
Message-ID: <wcc8zue31f7.fsf@world.std.com>#1/1
X-Deja-AN: 654021586
Sender: bobduff@world.std.com (Robert A Duff)
References: <87d7jvp3qq.fsf@chiark.greenend.org.uk>
 <wccwvhzbnwc.fsf@world.std.com> <8ma4lf$4g8$1@news-hrz.uni-duisburg.de>
Organization: The World Public Access UNIX, Brookline, MA
Newsgroups: comp.lang.ada
Date: 2000-08-03T00:00:00+00:00
List-Id: <comp.lang.ada>

sb463ba@l1-hrz.uni-duisburg.de (Georg Bauhaus) writes:

> Robert A Duff (bobduff@world.std.com) wrote:
> 
> : I don't like so-called literate programming for the same reason I don't
> : like C macros.  In order to understand the code, you have to imagine the
> : actual output of the macro preprocessor.
> 
> Agreed if literate programming  was about code, but it is
> not.  It is about English, about explaining algorithms in
> English (or your preferred human language), about not having
> to worry about the outcome of the processor because the
> processor takes care of that. Ideally, though.

Ideally, indeed!

I'm afraid we haven't quite gotten to the point where we can ignore the
code, and just pay attention to the English explanation of the code.
I doubt we ever will, in fact.

The other day I was reading Knuth's book about MMIX, his new RISC
version of the MIX machine code.  The book contains literate programs of
various sorts: an assembler, an interpreter, and so forth.

I found the English prose to be quite nice.  So literate programming
succeeded in that regard.

But I found the code itself to be difficult to understand, partly
because it's written in a (strange dialect of) C, and partly because
it's so heavily macro-fied, as literate programs always are.

One example: there was a piece of code containing a "break" to exit a
loop.  This piece of code was not contained in a loop.  Which loop is it
exiting, I wondered?  The only way to tell was to hand-expand the
macros.

In my opinion, loop exits should be physically contained within the loop
their exiting.  Even C has this level of error checking.  But literate
programming succeeded in defeating even this simple (and good) rule,
making the code less readable than raw C code.

> If the language has facilities to express your design the
> way you think about design, good.  Literate programming
> helpers can help with this.  I'm exaggerating, but ideally
                                   ^^^^^^^^^^^^
> you would not have to worry about the outcome of
> preprocessors, compilers, optimizers, anything.

exaggerating!  :-)

> Of course you should and Knuth, supposedly having coined
> the words "literate programming", has written one of the
> books about inputs and outcomes, and that you shoul know
> how to worry about them.

- Bob