Re: Literate Programming (Was: Comments are KILLING me)
- To: mathgroup at smc.vnet.net
- Subject: [mg37814] Re: [mg37768] Literate Programming (Was: Comments are KILLING me)
- From: Alexander Sauer-Budge <ambudge at MIT.EDU>
- Date: Wed, 13 Nov 2002 01:13:20 -0500 (EST)
- Sender: owner-wri-mathgroup at wolfram.com
Various Literate Programming (LP) tools, like noweb (<http://www.eecs.harvard.edu/~nr/noweb/>), are language independent so you might be able to use them with Mathematica at the cost of loosing interactivity. I think this is a somewhat inevitable loss, however, as one of the basic tenants of LP involves restructuring your program by reorganizing code fragments in a manner which more closely follows its exposition in a human language. An example from the noweb site, <The main program>= (<-U) main(argc, argv) int argc; /* number of arguments on UNIX command line */ char **argv; /* the arguments, an array of strings */ { <Variables local to main> prog_name = argv[0]; <Set up option selection> <Process all the files> <Print the grand totals if there were multiple files> exit(status); } demonstrates typical top-level reorganization. Everything delineated by brackets "<...>" references a code fragment, which themselves can reference other code fragments. I think Ross Williams's quote you gave reinforces this: 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. It seems to me that anything less than this is just a verbose commenting style. I would extrapolate from this comment that Mathematica would be a "language system" and that "literate programming tools" would be noweb, etc. The above example demonstrates a hierarchical reorganization of the program, which can be easily achieved in the Front End, or through an "outlining editor", like Emacs or jEdit. This aspect of LP itself can be enhanced with an LP editor like Leo (<http://personalpages.tds.net/~edream/front.html>). You can also use noweb with LyX in order to edit your code with screen-rendered TeX code in the documentation. If you really want to right code like the above example, you can always try emulating the LP style with something like theMainProgram=Module[{}, doFirstThing; doSecondThing; ]; doFirstThing=Module[{}, statement1; statement2; ]; etc, but I think this horribly obfuscates the code. Why not just makes these fragments full-fledged functions instead of merely code fragments and actually structure your notebook in a way that makes sense instead of using an external application to shuffle everything around? I try to structure my programs so that they are composed of many small functions, the largest of which is usually just half a screen long, but most of which are only several lines. This way, I can explain each function easily with a preceding text cell and can easily provide fine grain error and argument checking. I haven't had any problems with using comments inside my longer functions, so I use those occasionally when something still isn't quite clear. Usually any lack of clarity signals that I am trying to do too much with a single function. For the most part, my function definitions are an orderless collection since most of them are defined with SetDelayed, :=, so I am free to organize them in a sequence of groups that make sense. On Tuesday, November 12, 2002, at 03:13 AM, Nafod40 wrote: > 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. Except Mathematica is far more than its front end. It's a wonderfully sophisticated multi-paradigm programming language with excellent pattern-matching abilities, first-class functions and polymorphism just to name a few language features supporting an extensive library for "computer aided algebra". Nothing "mainstream" comes close to this combination, in my opinion. Best wishes in your quest for elegance and integration at all levels in your programming endeavors. Cheers! Alex P.S. You might find the opinions pertaining to Leo and LP at SlashDot interesting (<http://developers.slashdot.org/developers/02/08/28/ 1655207.shtml?tid=156>) if you skip over the usual drivel.