I've been looking into creating my own CPAN modules, reading a variety of perldoc (including perlmod, perlmodlib, and perlstyle) and nodes; however I still have several questions regarding the creation of flexible modules.

I should note that I'm approaching this from the perspective of the end user -- I'd like to implement the module to accept a variety of arguments presented in a variety of different ways; however I have several questions regarding the implementation.

Several nodes have recommended against shift @_, but I don't recall reading the reason for the recommendation. I'd presume there may be some conditions under which @_ is not locally scoped, but this is speculative.

Carp is a useful module, but at what point is carp or croak excessive? For example, if a sub expects a parameter, yet uses a default value should the code carp? From the perspective of the coder, I'd wager they knew what they were doing, but what of the end-user?

Are there instances where the organizational hierarchy should be sacrificed for brevity? Consider a module A::B::C with a member sub distorted_example_function. While I grant this example is intentionally abstract, it raises the question of the prudence of the hierarchy. While the argument could be made that the hierarchy itself should be reconsidered, this fails to address specialization and exclusivity. As a practical example, consider the module Engineering::Materials::Failure which offers a variety of failures based on the method of failure. Each of the failure methods could present a variety of functions to address a specific modus. The module structure seems ungainly at best, but is it prudent?

Prototypes are often discouraged, yet several CPAN modules feature them (albeit some with reservations). While I second this recommendation given TIMTOWDI, how does one code flexibly to provide for any number of permutations? A mathematical sub may be expected to compute a function given an input; however that input can take a variety of forms (a series of scalars, an array reference, a combination thereof, et all). While I have seen a few nodes and modules which are fairly flexible, I don't recall seeing any which support every permutation (even given the limitations of context and POD).

Tests seem to be a good idea, but how does one differentiate between the useful and the excessive? For example:

sub average { my ($min, $max) = @_; return ($min+$max)/2; }

I'm also intrigued by the notion of test-driven development, but given my limited understanding of the applicability of tests, this is not pheasible.

Suffice it to say, my foray into writing CPAN quality modules has left me with several questions regarding the perlstyle of CPAN modules. While I would appreciate responses to my questions above, I would also appreciate any other insights you may have regarding implementing TIMTOWDI-friendly modules.


In reply to Writing TIMTOWDI-friendly CPAN Modules by eibwen

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.