Comments are KILLING me
Nafod40
StandardForm, so the 1/10 term is written 1 on top of 10...
test := Module[(x = 1/10, (* now is the time *) y = 2}, x]
Using StandardForm and 2D mathematical typesetting, it works fine in
the notebook. Save it as a package and load it in, and I get a slew of
error messages...
\!\(InputForm\`Syntax::"sntxb" :
"Expression cannot begin with etc....
This is KILLING me! If the Front End has a bug in it, then make
comments illegal. If comments are OK, then fix the bug! I (am trying
to) use text, mathematical typesetting, and comments to provide a best
product to my customer. While text is great, there is certainly a time
and a place for comments within the code.
Does anyone have some sort of add-in such that the autopackage
function converts all cells to input form first? Or reconverts to
StandardForm? I don't need to carry any of the comments or formatting
into the *.m file, and prefer that none of it did. Wolfram, do you
guys have anything like this?
Why hasn't this been fixed?
Mike
Louis M. Pecora
I've been bitten by problems with comments, (legal) white space, and
Mathematica's autoformatting in the past. I gave up using all of them and then
eventually gave up using Mathematica for large coding projects. Luckily I
mostly do numerical work so other solutions will work for me. Sadly,
Mathematica remains a difficult environment to code and debug in. Sorry, I
have no solution for you only my own story.
--
Lou Pecora
- My views are my own.
Allan Hayes
I set your code (in 2D form)and put it into a .m file (1) by copying and
p[asting into a the file (2) by making the containing cell initializing and
using Edit>Copy Selection As>Package Format.
I then loaded the file using <<.
In both cases test evaluated with no problem.
Maybe I am missing something/
I am using Mathematica m.2
--
Allan
---------------------
Allan Hayes
Mathematica Training and Consulting
Leicester UK
www.haystack.demon.co.uk
h...@haystack.demon.co.uk
Voice: +44 (0)116 271 4198
Fax: +44 (0)870 164 0565
"Nafod40" <may...@psu.edu> wrote in message
news:aqfp6g$7d3$1...@smc.vnet.net...
Tom Burton
<may...@psu.edu> wrote:
> I can write a simple package with a single line of code written in
> StandardForm, so the 1/10 term is written 1 on top of 10...
>
> test := Module[(x = 1/10, (* now is the time *) y = 2}, x]
>
> Using StandardForm and 2D mathematical typesetting, it works fine in
> the notebook. Save it as a package and load it in, and I get a slew of
> error messages...
>
> \!\(InputForm\`Syntax::"sntxb" :
> "Expression cannot begin with etc....
>
> This is KILLING me!
Same goes for highlighting changes with color, font changes, etc. A serious
nuisance! Problems may lie dormant until you port to another platform. A
related issue is that when you process the code through the kernel (e.g.,
menu Cell, Convert To, StandardForm), this local formatting is stripped
away. This loss cannot be undone.
Wolfram Support has discouraged me from using all such "fragile"
constructions. Comments are the least of it really, because alternatives are
better for other reasons: (1) Divide code into small chunks interspersed
with explanatory material. (2) Use longer, self-descriptive names for
symbols.
The related issue above suggests a cure: Process the code through the
kernel, stripping out all local formatting, on the way to the m-file. This
change would "kill" folks who still look at m files. Still, if the
correction were that easy, WRI would have done by now :-) Perhaps the
instability is in the notebook. That would present a more difficult problem.
Tom Burton
Selwyn Hollis
Writing package code with a simple text editor can give you more
control, fewer headaches, and cleaner code faster.
---
Selwyn Hollis
Nafod40
> 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.
Jens-Peer Kuska
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
Selwyn Hollis
> Selwyn Hollis ...
>
>>
>>Writing package code with a simple text editor can give you more
>>control, fewer headaches, and cleaner code faster.
>
>
> 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.
You missed the point completely. You can write Mathematica code in a
text editor, and you can make it as "literate" as you like! The reason
you're having problems with comments is due to the fact that Mathematica
demands that package code be in InputForm (i.e., plain text), plus the
quirkiness of how Mathematica converts StandardForm to InputForm. So the
simplest way to have your code turn out pretty is to write it in
InputForm to begin with, and for that you may as well use a text editor.
Just give the file a .m extension and it will work like a charm.
---
Selwyn Hollis
David Park
endorse it. But there is a difference in emphasis between notebooks and
packages. If a notebook is written for someone else to read then the object
is to communicate in as clear a manner as possible and literate programming
is the order of the day. Packages are generally meant to provide
computational facilities and there literate programming is less important.
Instead good documentation is more important.
NOTEBOOKS
1) Use Text cells to explain what you are doing. The explanation is as
important as the code. You can start a Text cell by putting the selection
point between cells and typing Alt-7. Then start entering the text. Don't
use Input cells, or group headers for comments.
2) Use graphics to illustrate points. You can put the graphics code in a
closed cell when the code itself is not of interest.
3) Use Section and Subsection grouping with Automatic Grouping. Never use
Manual Grouping. Don't present a reader with a long unstructured notebook.
4) If you are trying to instruct as to method, write code in steps instead
of using highly nested one-liners. You can always wrap it up after the
explanation. You can put multiple steps in one cell where the use of % is
unambiguous.
5) Shy away from too much use of colored cells or text. This may be clear to
you but it is seldom clear to the reader who does not know the color coding
and is not going to spend a lot of time learning it. Good form is clear but
not a spectacle.
PACKAGES
1) If you want to make the package code and methods available to users use a
package notebook. You can use grouping and Text cells just as before. Here I
differ from Selwyn's advice. It is much easier to edit and change an
organized package notebook than a long text file. And you can include all
the text explanation you want. The grouping and text explanation disappear
in the package.m file, but there is no reason the user should look at that
anyway. He can look at the notebook.
2) It would be nice if Mathematica did not throw away delimited comments, (*
*), when a cell is converted to InputForm or StandardForm. I think that is a
design fault in Mathematica. Inline comments are useful because they point
to specific pieces of code, something that is difficult to do from a
preceding Text cell.
3) If you are ambitious, write documentation and individual Help pages with
examples for each command. It is not really that difficult to do. The Help
examples can also serve double duty as test notebooks. Unfortunately, most
packages do not have good documentation.
David Park
dj...@earthlink.net
http://home.earthlink.net/~djmp/
From: Nafod40 [mailto:may...@psu.edu]
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
Alexander Sauer-Budge
(<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.
Jens-Peer Kuska
> You missed the point completely. You can write Mathematica code in a
> text editor, and you can make it as "literate" as you like!
That's a joke ?
With literate programming you combine the documentation and the code
in a single document. In the comments and the description you can use
any plain TeX command. Have a look at
http://phong.informatik.uni-leipzig.de/~kuska/dirk.pdf
you can't do this with a simple text editor alone.
Notice that the main algorithm is human readable and only if
one really like to see what <Estimate the local error@> does
one can look at 10 lines of C-code :-)
Even for very simple C/C++ programs I prefer CWEB and
I love the system since I discover it 8 years ago.
Donald Knuth says that "literate programming" is the
best thing that came out of his TeX project and his favorite
programming language is -- CWEB
Regards
Jens
Albert REINER
>
> Selwyn Hollis ...
> > Just a remark:
> >
> > Writing package code with a simple text editor can give you more
> > control, fewer headaches, and cleaner code faster.
>
> I'm trying to follow the Literate Programming paradigm, whereby the
> you intersperse code with your documentation, not the other way
> around.
<http://www.agh.edu.pl/pub/tex/macros/mathematica/> might be of interest.
Albert.
.