Re: Documentation Methods and Efficiencies
- To: mathgroup at smc.vnet.net
- Subject: [mg100612] Re: Documentation Methods and Efficiencies
- From: "Scot T. Martin" <smartin at seas.harvard.edu>
- Date: Tue, 9 Jun 2009 03:56:20 -0400 (EDT)
- References: <h0d6s8$spq$1@smc.vnet.net> <200906070903.FAA28180@smc.vnet.net>
David, Leonid,
Thanks for this information and feedback. I have never used
SyntaxInformation[], and I'm just reading through this command now for the
first time. This is a very good tip. Thanks for bringing it to my
attention.
Actually, my case of documentation is even worse than outlined below,
mostly reflecting my incapacity to remember anything about today when
tomorrow comes. That is, I make heavy use of f::usage to write a paragraph
about f["phrase"]. Then, I use f["phrase"] in the code itself so that I
can follow the code without having to refer to my usage. I also richly
pepper everything with title cells and text cells. I probably spend about
as much time on all of this as I actually do on the coding of the problem.
All of this is great for me because I can pick up on my work in the
future, although I don't know if it helps anyone else to look at my untidy
f["phrase"] formulations.
I have also found f["phrase"] to be a very useful way to make a family of
related functions. That is, I will have f["phrase1"] and f["phrase2"] that
are related. This also helps me keep everything organized in my head. I
also like to do this with variables, e.g., data["from instrument 1"] and
data["from instrument 2"].
With SyntaxInformation[], now my functions can have paragraphs, phrases,
and grammar. :-) Boy, I love Mathematica.
Scot
On Mon, 8 Jun 2009, David Park wrote:
> 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?