Documentation Methods and Efficiencies
- To: mathgroup at smc.vnet.net
- Subject: [mg100608] Documentation Methods and Efficiencies
- From: "David Park" <djmpark at comcast.net>
- Date: Tue, 9 Jun 2009 03:55:36 -0400 (EDT)
- References: <h0d6s8$spq$1@smc.vnet.net> <200906070903.FAA28180@smc.vnet.net> <2018229.1244444141028.JavaMail.root@n11>
I'm starting this as a new thread because I'm shifting the topic even
further.
I'm not certain of the general effect of string comments, or regular
comments, (* *), or even the use of longer descriptive variable names on
efficiency. We can do some tests as below. Maybe somebody can provide more
information about this. I am pretty much in Scot's camp in wanting and
needing documentation for routines that I write.
There are many ways to produce documentation. One way is to always write a
usage message. It's easy to be lazy but usage messages are really useful,
not only because they provide information, but they also provide command
completion. Another way is to always write a SyntaxInformation statement.
These are again very useful when using the routines. If the routine has
options then it also pays to define them and include an OptionsPattern in
the SyntaxInformation. WRI has provided all these facilities, and except for
one thing, they are well designed. It will be more productive to use the WRI
documentationn facilities than design our own, and if the routines are
passed on to other users it will be easier for them.
Let's look at some cases:
f1::usage = "f1[x] returns x^2 + 1";
SyntaxInformation[f1] = {"ArgumentsPattern" -> {_}};
f1[x_] :=
Module[{work},
(* Square x *)
work = x^2;
(* Add one and return *)
work + 1]
Timing[Do[f1[RandomReal[]], {100000}]]
{0.951, Null}
But if we copy the f1 definition cell and then use Shift-Ctrl-I or
Shift-Ctrl-N or Shift-Ctrl-T to convert it to any of the various forms, we
lose the comments. I think this is an ill-designed feature of Mathematica.
It can catch a developer, who has carefully commented his code, by surprise.
(A developer might do this to clean up a much modified routine and restore
automatic indentation.)
So one idea might be to replace the (* *) comments by strings that do
nothing. They won't disappear if one changes the cell format. They appear to
have only a slight effect on efficiency.
f2::usage = "f2[x] returns x^2 + 1";
SyntaxInformation[f2] = {"ArgumentsPattern" -> {_}};
f2[x_] :=
Module[{work},
"Square of x";
work = x^2;
"Add one and return";
work + 1]
Timing[Do[f2[RandomReal[]], {100000}]]
{0.967, Null}
Then we come to Scot's method.
f3::usage = "f3[\"Take the square and add one\"][x] returns x^2 + 1";
f3["Take the square and add one"][x_] :=
Module[{work},
work = x^2;
work + 1]
Timing[Do[f3["Take the square and add one"][RandomReal[]], {100000}]]
{0.952, Null}
There doesn't appear to be a significant efficiency effect between these
methods. But the last method has disadvantages. We can't define
SyntaxInformation for the x portion of the definition. And will we have to
type in the information string every time we use the routine? Maybe we can
use command completion. But that doesn't work. Try it.
I believe that Mathematica could be improved if both the SyntaxInformation
and usage statement command completion allowed for subvalues. Subvalues are
very useful in separating parameters from variables. I don't see why there
should be an insuperable obstacle here.
Now we come back to more general documentation. In many applications it
would be good practice to not only write usage messages and
SyntaxInformation statements, and also use OptionsPattern when appropriate,
but also to actually incorporate many routines in packages and write Version
6 documentation pages for them using Workbench. Well, not for everything,
but for any routine that you might use in the future, or others might use;
for routines that are part of a major research project, or used in
courseware or in an electronic book. The function page has a place for
extensive notes on the usage. One could also include many test cases there,
and also extensive textual discussion and even developmental material. It
could certainly go beyond the standard WRI Function Help page. The advantage
is that one has a fixed and recognized place to place and obtain all the
information on a function. One doesn't have to search through old notebooks.
And what better time to set up the documentation than shortly after a
routine has been developed when the material is at hand? If the substance of
the work is being done anyway, then it makes sense to get it into the
standard documentation. It's not that much extra work, once we learn how to
use Workbench, and once WRI is willing to put a little more effort into it
and make Workbench convenient for something more than their internal
documentation.
David Park
djmpark at comcast.net
http://home.comcast.net/~djmpark/
From: Scot T. Martin [mailto:smartin at seas.harvard.edu]
On the general topic of performance, I'd be interested to know if anyone
can comment on the following. In an effort to keep my codes as reasonable
as possible, I use a lot of "sentence variables". What I mean is that I'll
write:
myfunction["further explanation"][var1_,var2_]:= ....
I add that extra string in naming the function. This helps me immensely to
remember what I'm doing and make my code accessible to me again in six
months. I have often wondered, however, if I slow down Mathematica by
using these long function names.
Does anyone know?
[For most of my applications, the limiting aspect on overall
implementation time is my slow human CPU, so I have ample computer cycles
and memory. However, there are a few applications that cause me to leave
my computer running overnight, so I'm wondering somewhat about the
performance of the code and if these long variable names are having an
effect.]
- References:
- Re: Why is recursion so slow in Mathematica?
- From: lshifr@gmail.com
- Re: Why is recursion so slow in Mathematica?