Edit: /usr/share/perl5/pod/perlmodstyle.pod (22575B)
=head1 NAME
perlmodstyle - Perl module style guide
=head1 INTRODUCTION
This document attempts to describe the Perl Community's "best practice"
for writing Perl modules. It extends the recommendations found in
L
, which should be considered required reading
before reading this document.
While this document is intended to be useful to all module authors, it is
particularly aimed at authors who wish to publish their modules on CPAN.
The focus is on elements of style which are visible to the users of a
module, rather than those parts which are only seen by the module's
developers. However, many of the guidelines presented in this document
can be extrapolated and applied successfully to a module's internals.
This document differs from L in that it is a style guide
rather than a tutorial on creating CPAN modules. It provides a
checklist against which modules can be compared to determine whether
they conform to best practice, without necessarily describing in detail
how to achieve this.
All the advice contained in this document has been gleaned from
extensive conversations with experienced CPAN authors and users. Every
piece of advice given here is the result of previous mistakes. This
information is here to help you avoid the same mistakes and the extra
work that would inevitably be required to fix them.
The first section of this document provides an itemized checklist;
subsequent sections provide a more detailed discussion of the items on
the list. The final section, "Common Pitfalls", describes some of the
most popular mistakes made by CPAN authors.
=head1 QUICK CHECKLIST
For more detail on each item in this checklist, see below.
=head2 Before you start
=over 4
=item *
Don't re-invent the wheel
=item *
Patch, extend or subclass an existing module where possible
=item *
Do one thing and do it well
=item *
Choose an appropriate name
=item *
Get feedback before publishing
=back
=head2 The API
=over 4
=item *
API should be understandable by the average programmer
=item *
Simple methods for simple tasks
=item *
Separate functionality from output
=item *
Consistent naming of subroutines or methods
=item *
Use named parameters (a hash or hashref) when there are more than two
parameters
=back
=head2 Stability
=over 4
=item *
Ensure your module works under C