It all depends on context.
::
is primarily necessary if there are namespace collisions, functions from different packages with the same name. When I load the dplyr
package, it provides a function filter
, which collides with (and masks) the filter
function loaded by default in the stats
package. So if I want to use the stats
version of the function, I'll need to call it with stats::filter
. This also gives motivation for not loading lots of packages. If you really only want one function from a package, it can be better to use ::
than load the whole package, especially if you know the package will mask other functions you want to use.
Not in code, but in text, I do find ::
very useful. It's much more concise to type stats::filter
than "the filter
function in the stats
package".
From a performance perspective, there is a (very) small price for using ::
. Long-time R-Core development team member Martin Maechler wrote (on the r-devel mailing list (Sept 2017))
Many people seem to forget that every use of ::
is an R
function call and using it is inefficient compared to just using
the already imported name.
The performance penalty is very small, on the order of a few microseconds, so it's only a concern when you need highly optimized code. Running a line of code that uses ::
one million times will take a second or two longer than code that doesn't use ::
.
As far as portability goes, it's nice to explicitly load packages at the top of a script because it makes it easy to glance at the first few lines and see what packages are needed, installing them if necessary before getting too deep in anything else, i.e., getting halfway through a long process that now can't be completed without starting over.
Aside: a similar argument can be made to prefer library()
over require()
. Library will cause an error and stop if the package isn't there, whereas require will warn but continue. If your code has a contingency plan in case the package isn't there, then by all means use if (require(package)) ...
, but if your code will fail without a package you should use library(package)
at the top so it fails early and clearly.
Within your own package
The general solution is to make your own package that imports
the other packages you need to use in the DESCRIPTION file. Those packages will be automatically installed when your package is installed, so you can use pkg::fun
internally. Or, by also importing them in the NAMESPACE
file, you can import
an entire package or selectively importFrom
specific functions and not need ::
. Opinions differ on this. Martin Maechler (same r-devel source as above) says:
Personally I've got the impression that :: is
much "overused" nowadays, notably in packages where I'd strongly
advocate using importFrom() in NAMESPACE, so all this happens
at package load time, and then not using ::
in the package
sources itself.
On the other hand, RStudio Chief Scientist Hadley Wickham says in his R Packages book:
It's common for packages to be listed in Imports
in DESCRIPTION
, but not in NAMESPACE
. In fact, this is what I recommend: list the package in DESCRIPTION
so that it’s installed, then always refer to it explicitly with pkg::fun()
. Unless there is a strong reason not to, it's better to be explicit.
With two esteemed R experts giving opposite recommendations, I think it's fair to say that you should pick whichever style suits you best and meets your needs for clarity, efficiency, and maintainability.
If you frequently find yourself using just one function from another package, you can copy the code and add it to your own package. For example, I have a package for personal use that borrows %nin%
from the Hmisc
package because I think it's a great function, but I don't often use anything else from Hmisc
. With roxygen2
, it's easy to add @author
and @references
to properly attribute the code for a borrowed function. Also make sure the package licenses are compatible when doing this.