R devel - Aug 2005 - Functions with the same name: best practices

Ok, here's another best practices question - let's say I'm writing a
package and I want to use a function name that is already claimed by a
function in the base R packages.  For the sake of argument, let's
pretend this function is for profiling the performance of a function
(like Rprof for example), and so an obvious name that comes to mind is
profile.  This, of course, clashes with the built in profile for
"investigating behavior of objective function near the solution
represented by fitted."

A little thinking and a quick survey of other packages reveal some
possible solutions:

 * capitalise the function differently (eg. Profile)
 * use a prefix/suffic (eg. Rprof)
 * use a thesaurus
 * use namespaces (and rely on others to use namespaces correctly in
their code/packages)

What would you suggest?

Thanks again,

Hadley

On 8/22/05, hadley wickham <h.wickham at gmail.com>
wrote:
> Ok, here's another best practices question - let's say I'm
writing a
> package and I want to use a function name that is already claimed by a
> function in the base R packages.  For the sake of argument, let's
> pretend this function is for profiling the performance of a function
> (like Rprof for example), and so an obvious name that comes to mind is
> profile.  This, of course, clashes with the built in profile for
> "investigating behavior of objective function near the solution
> represented by fitted."
> 
> A little thinking and a quick survey of other packages reveal some
> possible solutions:
> 
>  * capitalise the function differently (eg. Profile)
>  * use a prefix/suffic (eg. Rprof)
>  * use a thesaurus
>  * use namespaces (and rely on others to use namespaces correctly in
> their code/packages)
> 
> What would you suggest?
> 
profile is a generic so if your function has the same purpose but for a 
different class you can just create a new method.

It depends on the example, as you might guess.

profile() is a generic function in stats.  Namespaces are not going to 
help there, as it is normally called by users (it is also called by some 
confint() methods, and that will be protected by namespaces).

For functions intended to be used by end-users, I think there is little 
choice but to have distinct names.  For other functions, you would not 
need to export them from the namespace of your package, and then probably 
the nameclash would be of little consequence.  However, even there beware 
of examples like Adai's with 'df', where model.frame() found that
object
in the package rather than in his workspace.

On Mon, 22 Aug 2005, hadley wickham wrote:
> Ok, here's another best practices question - let's say I'm
writing a
> package and I want to use a function name that is already claimed by a
> function in the base R packages.  For the sake of argument, let's
> pretend this function is for profiling the performance of a function
> (like Rprof for example), and so an obvious name that comes to mind is
> profile.  This, of course, clashes with the built in profile for
> "investigating behavior of objective function near the solution
> represented by fitted."
>
> A little thinking and a quick survey of other packages reveal some
> possible solutions:
>
> * capitalise the function differently (eg. Profile)
> * use a prefix/suffic (eg. Rprof)
> * use a thesaurus
> * use namespaces (and rely on others to use namespaces correctly in
> their code/packages)
>
> What would you suggest?
>
> Thanks again,
>
> Hadley
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>
-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

hadley wickham wrote:
> Ok, here's another best practices question - let's say I'm
writing a
> package and I want to use a function name that is already claimed by a
> function in the base R packages.  For the sake of argument, let's
> pretend this function is for profiling the performance of a function
> (like Rprof for example), and so an obvious name that comes to mind is
> profile.  This, of course, clashes with the built in profile for
> "investigating behavior of objective function near the solution
> represented by fitted."
> 
> A little thinking and a quick survey of other packages reveal some
> possible solutions:
> 
>  * capitalise the function differently (eg. Profile)
>  * use a prefix/suffic (eg. Rprof)
>  * use a thesaurus
>  * use namespaces (and rely on others to use namespaces correctly in
> their code/packages)
> 
> What would you suggest?
You should use a namespace.  It will protect your code against someone 
else using one of your function names.

If the function is for internal use only, that's sufficient.  If you 
want to export the function, you should try to avoid conflicting with 
existing functions that you expect users to have installed, because it 
becomes quite inconvenient to users:  their scripts depend on the load 
order of packages unless they put <pkg>:: in front of each call.

I think using a thesaurus would be best (if by that you mean choosing a 
different name that still describes the function), but will often fail, 
in which case I'd use the prefix/suffix decoration.  Changing only 
capitalization makes it nearly impossible to talk about your function 
without confusion.

Duncan Murdoch

Thanks to all of you for your advice. I will read up on namespaces and
start using them to "protect" my internal function from name clashes
with other packages, and endeavour to my public functions unique
names.

I know other languages (eg. python) separate loading a package and
including it in the default namespace, do you think R will ever move
to such a system?

Thanks,

Hadley