[Rd] Advice on Namespaces

[Duncan Murdoch]

On 12-09-10 12:11 PM, Bert Gunter wrote:
> Hi Folks:
>
> I'm writing a little package that may not ever hit CRAN or even be
> distributed beyond a relatively narrow audience at my company.
> Nevertheless, I have tried to adhere to practices that would work if
> it were. With that in mind, I have read the Writing R Extensions
> Manual (and my humble kudos to its writers, as it has  successfully
> guided even an ignoramus like myself ) and Luke Tierney's R Newsletter
> documentation on Namespaces. However, it is still not clear to me (see
> above ignoramus comment!) what functions -- and especially which S3
> methods whose generics I define in my package -- should be exported
> and which should not. Perusing other packages also didn't reveal any
> clear patterns from which I could infer best practice.
>
> So may I ask for advice or any references that would provide such
> guidelines. Feel free to keep replies private if this query in not
> appropriate for this list. Many thanks.

If you export it, then you need to document it, and it needs to be 
usable by others.

Often you'll have specialized functions in a package that do what you 
need, but they are too specialized to be useful to others:  don't export 
those.

Once you export a function, people (or maybe just yourself in some other 
package or script) will start using it, so you tend to get locked in to 
the interface.  So don't export functions unless you want to support 
them in their current form for the life of the package.

If you export a function with the same name as one exported from another 
package, it becomes inconvenient to use either function once both 
packages are attached.  (Which one you get depends on the order of 
attaching the packages.) So don't export trivial functions, and think 
carefully about the names you use for the ones you do export.

It is slightly less convenient to test or inspect functions if you don't 
export them (you need the package:::foo style to refer to them from the 
console).  So during early development, you may want to export more, and 
limit the exports when you are happy with the package.

Duncan Murdoch