Best practice for naming of options

[Andrew Moylan]

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?

[David Park]

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
dj...@earthlink.net
http://home.earthlink.net/~djmp/

[Andrew Moylan]

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...@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...@earthlink.nethttp://home.earthlink.net/~djmp/

[Philipp]

David,

I think you're missing the point a bit.

MySpaceScaleFunction type symbol names for options are fine until (as
Andrew points out) someone writes a package with a symbol that has
exactly the same name (hey, you came with it, so could anyone else).
Making the name longer only decreases the probability of conflict, it
does not remove it.

Andrew is asking for a methodology to avoid conflicts between
"packaged" symbols.

I don't have an answer, the only heuristic I can offer is "When in
doubt, use full context names for symbols".

Cheers
Philipp