Re: Re: Best practice for naming of options
- To: mathgroup at smc.vnet.net
- Subject: [mg71536] Re: [mg71518] Re: Best practice for naming of options
- From: Andrzej Kozlowski <akoz at mimuw.edu.pl>
- Date: Wed, 22 Nov 2006 05:22:18 -0500 (EST)
- References: <ejtd4d$ijf$1@smc.vnet.net> <200611211205.HAA17914@smc.vnet.net>
The problem with using the same option name for a number of different functions is that help message for the option will have to be either vague in ?Method Method is an option to Solve, related functions, and various numerical \ functions, which specifies what algorithm to use in evaluating the result. or unnecessarily long (David Park once demonstrated a clever way of writing option help usage so that the help usage for an option will not override a message for another option with the same name but for a different function but append it to the new one). Not also that the packages, even standard ones like the NumericalMath package "do not count" as built in functions and do not always follow the conventions of Mathematica built-in functions. Some of them were written a very long time ago and revised only to keep them compatible with more recent versions of Mathematica. So there is no built in option with the name "Terms" in Mathematica. Try: ?*Terms* System` FactorTerms, FactorTermsList, NSumExtraTerms,NSumTerms At lest this seems to be quite consistent and the usage messages are no longer vague: ?NSumExtraTerms "NSumExtraTerms is an option for NSum which is used with the method Fit. NSumExtraTerms -> n uses n terms in the extrapolation process. NSumExtraTerms must be greater than twice WynnDegree." I suspect that the reason for having just one rather vague user message for Method is that the average user is not expected to use this option very much. Andrzej Kozlowski On 21 Nov 2006, at 21:05, Andrew Moylan wrote: > Hi David, > > Thanks for your reply. I agree that using a name like > MySpaceScaleFunction appears to be the best possible solution. > > As for what is wrong with it: it's that it appears to be inconsistent > with the option naming conventions employed throughout Mathematica. > For > example, in Mathematica we have the option Method, and we don't have > the options NIntegrateMethod or NLimitMethod, even though the values > that may be used for the Method option are completely different in the > cases of NIntegrate and NLimit. In both cases "Method" is the best > possible name. > > In constrast, I think it is unfortunate that, whereas the functions > NLimit, ND, and EulerSum all expose an option called Terms (a clear, > unambiguous, intuitive name), the function NSum instead exposes an > option called NSumTerms. What do you think? > > Regards, > Andrew > > > On Nov 21, 10:18 am, "David Park" <d... at earthlink.net> wrote: >> Andrew, >> >> What is wrong with using a name like MySpaceScaleFunction, or >> assuming that >> the option is actually associated with some function Foo, >> FooScaleFunction? >> You say that it produces cumbersome option names but if you have a >> usage >> message for it one can then use command completion Ctrl-K to bring >> up the >> options or routines that start with Foo say. So it is not all that >> cumbersome, and having longer specific names vastly cuts down on the >> possibility of conflicts. In my opinion, longer specific names are >> much >> better than short ambiguous names. >> >> David Park >> d... at earthlink.nethttp://home.earthlink.net/~djmp/ >> >> From: Andrew Moylan [mailto:andrew.j.moy... at gmail.com] >> >> Hi all, >> >> When writing my own functions that use options, I sometimes have a >> problem where option names become shadowed by other packages that are >> loaded later. For example, I might want to use an option called >> ScaleFunction: >> >> BeginPackage["MySpace`"]; >> ScaleFunction::"usage" = "hello"; >> EndPackage[]; >> >> Needs["Graphics`"] >> >> Now the name ScaleFunction is shadowed by the option of the same name >> from the Graphics package: >> >> Evaluating >> ? ScaleFunction >> gives >> Graphics`Common`GraphicsCommon`ScaleFunction >> >> I can think of two possible solutions to this problem, each with a >> different problem: >> >> (1) I could try to always choose unique names for my options. This >> produces cumbersome option names and in any case only works until >> I or >> someone else writes a package with that option name. >> >> (2) I could use _strings_ for option names instead of symbols: >> Func["ScaleFunction" -> x] instead of Func[ScaleFunction -> x]. I >> have >> seen this done sometimes in the built-in Mathematica functions. >> Unfortunately, with this approach it no longer becomes possible to >> define usage text for options in the usual way: >> >> "ScaleFunction"::usage = "ScaleFunction is an option to Func that >> ..."; >> gives the warning >> Message::name : Message name ScaleFunction::usage is not of the >> form >> \ >> symbol::name or symbol::name::language. >> >> Is there a way to get the best of both worlds (define usage >> strings AND >> ensure that option names don't become shadowed)? >> >> Cheers, >> Andrew >> >> P.S. I observe that the built-in function NSum has an option called >> NSumTerms. I think this option would be better called Terms. Could it >> be that the writers of that function faced the same dilemma that I am >> facing? >
- References:
- Re: Best practice for naming of options
- From: "Andrew Moylan" <andrew.j.moylan@gmail.com>
- Re: Best practice for naming of options