Services & ResourcesWolfram ForumsMathGroup Archive

[Date Index] [Thread Index] [Author Index]

Re: Literate Programming (Was: Comments are KILLING me)

• To: mathgroup at smc.vnet.net
• Subject: [mg37784] Re: Literate Programming (Was: Comments are KILLING me)
• From: Jens-Peer Kuska <kuska at informatik.uni-leipzig.de>
• Date: Wed, 13 Nov 2002 01:10:47 -0500 (EST)
• Organization: Universitaet Leipzig
• References: <aqfp6g$7d3$1@smc.vnet.net> <200211101038.FAA11813@smc.vnet.net> <aqo078$fpe$1@smc.vnet.net> <aqqdit$seq$1@smc.vnet.net>
• Reply-to: kuska at informatik.uni-leipzig.de
• Sender: owner-wri-mathgroup at wolfram.com

Hi,

the only thing that you can't do with Mathematica but with CWEB
or any other system for literate programming is to name code snippets,
i.e.,

myFunction[x_,opts___]:=
  Module[{y,z},
    @<Process the options@>@;
    @<Check the options@>@;
    @<Do something usefull@>@;
   ]

I have often missed this feature, but it need a preprocessor.
It is relative easy to simulate this behaviour by Block[]
and several Mathematica functions

myFunction[x_,opts___]:=
  Block[{y,z},
    ProcessTheOptions[{opts}];
    CheckTheOptions[{y,z}];
    DoSomethingUsefull[x,y,z]
   ]

You need a Block[] here to have access to the local
variables.

If you work with notebooks, you can comment every 
of your functions with a Text cell 
including formulas and descriptions.

Regards
  Jens




Nafod40 wrote:
> 
> Selwyn Hollis ...
> > Just a remark:
> >
> > Writing package code with a simple text editor can give you more
> > control, fewer headaches, and cleaner code faster.
> 
> Ahhh, but that would completely remove my main purpose for using
> Mathematica. If I was to just write standard source code, I would do
> it in something far less quirky and much more in the mainstream than
> Mathematica.
> 
> I'm trying to follow the Literate Programming paradigm, whereby the
> you intersperse code with your documentation, not the other way
> around. To quote it's originator, Donald Knuth (of TeX and "Art Of
> Programming" fame) from http://www.literateprogramming.com/
> 
> ***************
> 
> Donald Knuth. "Literate Programming (1984)" in Literate Programming.
> CSLI, 1992, pg. 99.
> 
> I believe that the time is ripe for significantly better documentation
> of programs, and that we can best achieve this by considering programs
> to be works of literature. Hence, my title: "Literate Programming."
> 
> Let us change our traditional attitude to the construction of
> programs: Instead of imagining that our main task is to instruct a
> computer what to do, let us concentrate rather on explaining to human
> beings what we want a computer to do.
> 
> The practitioner of literate programming can be regarded as an
> essayist, whose main concern is with exposition and excellence of
> style. Such an author, with thesaurus in hand, chooses the names of
> variables carefully and explains what each variable means. He or she
> strives for a program that is comprehensible because its concepts have
> been introduced in an order that is best for human understanding,
> using a mixture of formal and informal methods that reinforce each
> other.
> 
> *********************
> 
> Another great quote...
> 
> Ross Williams. FunnelWeb Tutorial Manual, pg 4.
> 
> A traditional computer program consists of a text file containing
> program code. Scattered in amongst the program code are comments which
> describe the various parts of the code.
> 
> In literate programming the emphasis is reversed. Instead of writing
> code containing documentation, the literate programmer writes
> documentation containing code. No longer does the English commentary
> injected into a program have to be hidden in comment delimiters at the
> top of the file, or under procedure headings, or at the end of lines.
> Instead, it is wrenched into the daylight and made the main focus. The
> "program" then becomes primarily a document directed at humans, with
> the code being herded between "code delimiters" from where it can be
> extracted and shuffled out sideways to the language system by literate
> programming tools.
> 
> The effect of this simple shift of emphasis can be so profound as to
> change one's whole approach to programming. Under the literate
> programming paradigm, the central activity of programming becomes that
> of conveying meaning to other intelligent beings rather than merely
> convincing the computer to behave in a particular way. It is the
> difference between performing and exposing a magic trick.
> 
> ******************
> 
> Mathematica has the right balance of documentation and codability to
> fully support this paradigm if it would JUST WORK AS ADVERTISED.

• References:
  • Re: Comments are KILLING me
    • From: "Allan Hayes" <hay@haystack.demon.co.uk>