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