Re: conditional compilation

[Florian Weimer <fw@deneb.enyo.de>]

Robert A Duff <bobduff@world.std.com> writes:

> Simon Brady <see@below.for.email.address> writes:
> 
> > Been there, done that... I think the literate programming crowd offer a
> > useful insight here: programs aren't the same thing as representations
> > of programs, and what the compiler sees isn't necessarily what the
> > programmer should see.
> 
> 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.  (I admit that C macros are the
> worse of the two, of course.)

I think this argument is valid only to a limited extent.  After all,
there are plenty of language constructs which can be used to hide
details, and if a programmer has hidden the wrong details, this will
always make maintenance unnecessarily complicated.

Of course, the C preprocessor is bad, and its usage results in quite
a lot of bugs.  (IIRC the study carried out by Bell Labs on some of
their telephone switching software showed this quite drastically.)

Many of them are extremely non-obvious because there are many common
idioms associated with C macros which you tend to ignore when
reading the source, but which are quite intrusive and can cause
bugs by itself.  For example, after a while, you start to overlook
the "do { ... } while (0);" construct to make a macro expansion a
statement---until a "continue;" statement is part of the macro, which
is supposed to effect an outer loop. :-/ (I guess C macros are used
quite regularly to obfuscate flow of control because you can't use
subroutines for that.)

I don't have any experience in maintaining literate programs, but
the last time I tried to read such code, the algorithms were in fact
nicely documented, but even at the lower levels, the data flow was
very hard to trace even locally (in contrast to the control flow,
which was properly outlined, but which you could hide as well).  In
my experience, understanding the data flow is quite important if you
want to do some non-trivial changes to existing code.  I doubt that
the literate programming approach as exemplified by TeX is really that
maintainer-friendly.  If you are interested in such stuff, TeX is
very nice to read, but it's generally considered a dead end regarding
future development.  In fact, TeX has already been reimplemented in
Java, AFAIK not in strict literate programming style.  (Well, this
reimplementation is also an involuntary case study in the portability
of Java code with rather disappointing results.)

> In any case, from a language design point of view, if you think the
> compiler should see things in a different order or different
> organization than human beings, then clearly the programming language is
> poorly designed.  

This is a very good point.  On the other hand, with most programming
languages, you need some separate documentation for the overall
structure of the code, general design decision and so on.  AFAIK
literate programming tries to merge this kind of documentation with
the actual code.