Re: [boost] Re: Review: Boost Coding Guidelines

From: John Max Skaller (skaller_at_[hidden])
Date: 2001-07-26 19:19:30

David Abrahams wrote:
> 
> ----- Original Message -----
> From: "John Max Skaller" <skaller_at_[hidden]>
> 
> > The effect of what appears to be, on the surface,
> > a subtle distinction is fundamental: LP requires a total
> > committment.Code extractors usually work on unprepared code,
> > though the results may not be pleasing.
> 
> Having never done any LP, I wonder about the effect it may have on process:
> often writing new code requires building up the code from a "sketch",
> usually with only terse comments, then making the documentation more robust
> later. Does an LP approach interfere with that, aid it, or is it neutral?

        I'd say it supports it. In particular, I use this
technique myself. Typically, I write // comments in the code
more often than 'documentation', and lift some of them out
later. But I also write 'explanations' of interesting
points of the design in the natural language part of the
LP source: I'm mainly talking to myself to try to figure
out the design.

        To put this another way: here is a typical
interscript 'starting out' C++ file:

        @head(1,'Boost Algorithms')
        I provide a few auxilliary algos missing from
        the C++ Standard.

        @h = tangler('boost/myalgorithms.hpp')
        @select(h)
        #include <algorithm>
        template<class T> .....
        .....
        ..

There are 6 lines which aren't C++ code, the rest is
written just as if you weren't using LP at all.
A typical LP file has two code files: one for the
interface, one for the implementation.

To build a library from several such files:

        @set_title('boost')
        @head(1,'Boost')
        Boost is a C++ template library.
        @include_file('algos.ipk')
        @include_file('functions.ipk')
        @include_file('regex.ipk')
        @include_file('regression_tests.ipk')
        @include_file('build_script.ipk')

What you get when you tangle this is the complete boost system
(the dependency checking means that only changed files
are processed -- yes, it does introduce some delay)

When you weave, you get a complete web site for a program
listing. (or latex document, if you prefer).

To send someone the program, just zip up all the .ipk files.

To clean: delete everything other than the LP directory.

Obviously, this is a minimal use of LP. Which is about what
I tend to use: having written a very powerful system,
I rarely use the advanced features heavily.

The advantage is, for a very small cost, the complete project
structure exists right from the beginning: the documentation
is cursory, but you don't have to 'start' a new documentation
job, just fill out the existing structure, perhaps adding
a 'doco only' file, and perhaps refactoring a bit.

And, occasionally, one needs a powerful language to
'meta-program' with to generate lots of code from a small
concept data base, and Python is much better at doing that
than even C++ templates. And it works for C, C++,
Perl, Makefiles, documentation, unix shell, and anything 
else including Python .. and of course interscript!

So I guess you could say that the 'packaging' features
are important, not just 'documentation and code'.

-- 
John (Max) Skaller, mailto:skaller_at_[hidden] 
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
New generation programming language Felix  http://felix.sourceforge.net
Literate Programming tool Interscript     
http://Interscript.sourceforge.net