Namespaces

Namespaces

Namespaces control what functions and methods that your package exports for use by others. Namespaces make it easier to come up with your own function names without worrying about what names other packages have used. A namespace means you can use any name you like for internal functions, and when there is a conflict with an exported function, there is a standard disambiguation procedure.

The easiest way to use namespaces is with roxygen, because it keeps the namespace definitions next to the function that it concerns. The translation between roxygen tags and NAMESPACE directives is usually straightforward: the tag becomes a function name and its space-separated arguments become comma separated arguments to the function. For example @import plyr becomes import(plyr) and @importFrom plyr ddply becomes importFrom(plyr, ddply). The chief exception is @export which will automatically figure out the function name to export.

Exporting

It's not always easy to tell whether or not a function is internal or external. A few rules of thumb:

• Is the purpose of the function different to the purpose of the package? If not, make it internal. (A package should provide a set of closely related functions for a well-defined problem domain - someone should be able to look at all the functions in your package and say this is a package about X - if not, you should consider splitting it up into two packages)

• Does the function have a clear purpose and can you easily explain it? Every external function needs to be documented, and there's an implicit contract that that function will continue to exist in the future. If that's not the case, don't export it.

If a function isn't exported, you don't need to document it. This doesn't mean you shouldn't document it, but you only need to if it's complicated enough that you think you won't remember what it does.

To export a function, add the roxygen @export tag.

To export a method for a S3 generic function, add S3method roxygen tag: @S3method function class

You may also want to make the distinction between functions for users and functions for other developers. Functions that might be useful for developers or power users should be exported, but tagged with @keywords internal so they don't show up in routine lists of function documentation.

Importing

In your package DESCRIPTION there are two ways to indicate that you package requires another package to work: by listing it in either Depends or Imports. Depends works just like using library to load a package, but Imports is a little more subtle: the dependency doesn't get loaded in a way the user can see. This is good practice because it reduces the chances of conflict, and it makes the code clearer by requiring that every package used be explicitly loaded. For example, ggplot2 currently depends on the plyr package - this means that once you've loaded ggplot2, you don't need to load plyr to get access to (e.g) ddply. This is bad because you can't see which packages a block of code uses.