Services & ResourcesWolfram ForumsMathGroup Archive

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

Literate Programming (Was: Comments are KILLING me)

• To: mathgroup at smc.vnet.net
• Subject: [mg37768] Literate Programming (Was: Comments are KILLING me)
• From: may106 at psu.edu (Nafod40)
• Date: Tue, 12 Nov 2002 03:13:23 -0500 (EST)
• References: <aqfp6g$7d3$1@smc.vnet.net> <200211101038.FAA11813@smc.vnet.net> <aqo078$fpe$1@smc.vnet.net>
• Sender: owner-wri-mathgroup at wolfram.com

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.

• Follow-Ups:
  • Re: Literate Programming (Was: Comments are KILLING me)
    • From: Selwyn Hollis <selwynh@earthlink.net>

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