How should I reference functions in imported packages?

Question

When creating an R package, there are at least two alternatives for referencing functions in imported packages.

Either,

1. Explicitly name the function using the double colon operator whenever you call it, package::function.

2. Add importFrom(package, function) to the NAMESPACE file, either directly or via an #' @importFrom package function roxygen tag.

What are the advantages and disadvantages of each method?

Are there any technical differences in what each syntax achieves?

Answer 1

Arguments in favour of using package::function

It makes it completely clear where the function has come from.

Arguments in favour of using @importFrom package function

It involves less typing, particularly when a function is used many times by your package.

Since it involves looking up the package and a call to the :: function, package::function has a small runtime performance penalty. See https://stackoverflow.com/a/7283511/134830.

On balance, what's the verdict?

Both methods do the job and arguments either way aren't overwhelming, so don't lose sleep over this. Just pick one method and stick to it.

The policy that has been adopted at my place of work is that for a few commonly used packages, @importFrom roxygen tags should be used. For example, developers are expected to know that ddply comes from plyr, or functions beginning str_ come from stringr. In this case, the explicit parentage of the function isn't as useful to know. For functions outside this core list, (or if there is any ambiguity) :: should be used to make it clear where it came from.