Because Perl doesn't have true method privacy, Perl developers can mean more than one thing when they talk about a "private" sub/method.

Sometimes they mean a sub which is not to be used at all outside the module it was defined in. In these cases, I'd suggest you should at least consider making it into a coderef instead of a named sub, so that it cannot be used elsewhere (PadWalker trickery notwithstanding).

my $run_end = sub {
   my $self = shift;
   ...;
};

sub some_public_method {
   my $self = shift;
   ...;
   $self->$run_end();
}

[download]

Unless it's really obvious what it does, document its purpose in comments. The question of whether you should test it or not becomes moot — it cannot be used outside the module, so your test scripts can't directly touch it anyway. Any problems which affect the rest of the module should be exposed when you test the public API. Any problems which don't affect the rest of the module probably don't matter.

Other times, there are functions you have in one class/module that are not intended to be called by end users, but might be called by other classes/modules within your distribution, or overridden by subclasses within your distribution. This is racism. Don't do this. Well, okay, not racism, but that got your attention. It's still discriminating against other modules/classes because they weren't written by you. If it's a function/method which you have found useful/necessary, then other people might find it useful/necessary too, so make it part of your public API. Okay, so maybe it's pretty obscure and 99% of end users won't need it, and you don't want it cluttering up your documentation, but in that case, mention it in a separate "ADVANCED API" section of the documentation (perhaps even in a separate pod file) or document it fully in the comments, making it clear that it's a supported albeit obscure part of your API.

See also: the middle part of my presentation at the 2014 London Perl Workshop (and there's a cringy video of it on YouTube too).

toby döt ink

In reply to Re: (How) Do you document/test your private subroutines? by tobyink
in thread (How) Do you document/test your private subroutines? by stevieb

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.