How should I reference functions in imported packages?
namespaces, r, roxygen2
Solution
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.
Problem
When creating an R package, there are at least two alternatives for referencing functions in imported packages. Either, Explicitly name the function using the double colon operator whenever you call it, `package::function`. 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?