[Rd] Advice on Namespaces

[Bert Gunter]

Thanks Duncan. This was very helpful.

-- Bert

On Tue, Sep 11, 2012 at 4:05 AM, Duncan Murdoch
<murdoch.duncan at gmail.com> wrote:
> 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



-- 

Bert Gunter
Genentech Nonclinical Biostatistics

Internal Contact Info:
Phone: 467-7374
Website:
http://pharmadevelopment.roche.com/index/pdb/pdb-functional-groups/pdb-biostatistics/pdb-ncb-home.htm