1N/Aperlmodstyle - Perl module style guide
1N/AThis document attempts to describe the Perl Community's "best practice"
1N/Afor writing Perl modules. It extends the recommendations found in
1N/AL<perlstyle> , which should be considered required reading
1N/Abefore reading this document.
1N/AWhile this document is intended to be useful to all module authors, it is
1N/Aparticularly aimed at authors who wish to publish their modules on CPAN.
1N/AThe focus is on elements of style which are visible to the users of a
1N/Amodule, rather than those parts which are only seen by the module's
1N/Adevelopers. However, many of the guidelines presented in this document
1N/Acan be extrapolated and applied successfully to a module's internals.
1N/AThis document differs from L<perlnewmod> in that it is a style guide
1N/Arather than a tutorial on creating CPAN modules. It provides a
1N/Achecklist against which modules can be compared to determine whether
1N/Athey conform to best practice, without necessarily describing in detail
1N/AAll the advice contained in this document has been gleaned from
1N/Aextensive conversations with experienced CPAN authors and users. Every
1N/Apiece of advice given here is the result of previous mistakes. This
1N/Ainformation is here to help you avoid the same mistakes and the extra
1N/Awork that would inevitably be required to fix them.
1N/AThe first section of this document provides an itemized checklist;
1N/Asubsequent sections provide a more detailed discussion of the items on
1N/Athe list. The final section, "Common Pitfalls", describes some of the
1N/Amost popular mistakes made by CPAN authors.
1N/A=head1 QUICK CHECKLIST
1N/AFor more detail on each item in this checklist, see below.
1N/A=head2 Before you start
1N/ADon't re-invent the wheel
1N/APatch, extend or subclass an existing module where possible
1N/ADo one thing and do it well
1N/AChoose an appropriate name
1N/AAPI should be understandable by the average programmer
1N/ASimple methods for simple tasks
1N/ASeparate functionality from output
1N/AConsistent naming of subroutines or methods
1N/AUse named parameters (a hash or hashref) when there are more than two
1N/AEnsure your module works under C<use strict> and C<-w>
1N/AStable modules should maintain backwards compatibility
1N/AWrite documentation in POD
1N/ADocument purpose, scope and target applications
1N/ADocument each publically accessible method or subroutine, including params and return values
1N/AGive examples of use in your documentation
1N/AProvide a README file and perhaps also release notes, changelog, etc
1N/AProvide links to further information (URL, email)
1N/A=head2 Release considerations
1N/ASpecify Perl version requirements with C<use>
1N/AInclude tests with your module
1N/AChoose a sensible and consistent version numbering scheme (
X.YY is the common Perl module numbering scheme)
1N/AIncrement the version number for every change, no matter how small
1N/APackage the module using "make dist"
1N/A=head1 BEFORE YOU START WRITING A MODULE
1N/ATry not to launch headlong into developing your module without spending
1N/Asome time thinking first. A little forethought may save you a vast
1N/Aamount of effort later on.
1N/A=head2 Has it been done before?
1N/AYou may not even need to write the module. Check whether it's already
1N/Abeen done in Perl, and avoid re-inventing the wheel unless you have a
1N/AGood places to look for pre-existing modules include
1N/AIf an existing module B<almost> does what you want, consider writing a
1N/Apatch, writing a subclass, or otherwise extending the existing module
1N/Arather than rewriting it.
1N/A=head2 Do one thing and do it well
1N/AAt the risk of stating the obvious, modules are intended to be modular.
1N/AA Perl developer should be able to use modules to put together the
1N/Abuilding blocks of their application. However, it's important that the
1N/Ablocks are the right shape, and that the developer shouldn't have to use
1N/Aa big block when all they need is a small one.
1N/AYour module should have a clearly defined scope which is no longer than
1N/Aa single sentence. Can your module be broken down into a family of
1N/A"
FooBar.pm provides an implementation of the FOO protocol and the
1N/Arelated BAR standard."
1N/Aimplements the related BAR protocol."
1N/AThis means that if a developer only needs a module for the BAR standard,
1N/Athey should not be forced to install libraries for FOO as well.
1N/A=head2 What's in a name?
1N/AMake sure you choose an appropriate name for your module early on. This
1N/Awill help people find and remember your module, and make programming
1N/Awith your module more intuitive.
1N/AWhen naming your module, consider the following:
1N/ABe descriptive (
i.e. accurately describes the purpose of the module).
1N/ABe consistent with existing modules.
1N/AReflect the functionality of the module, not the implementation.
1N/AAvoid starting a new top-level hierarchy, especially if a suitable
1N/Ahierarchy already exists under which you could place your module.
1N/AYou should contact modules@perl.org to ask them about your module name
1N/Abefore publishing your module. You should also try to ask people who
1N/Aare already familiar with the module's application domain and the CPAN
1N/Anaming system. Authors of similar modules, or modules with similar
1N/Anames, may be a good place to start.
1N/A=head1 DESIGNING AND WRITING YOUR MODULE
1N/AConsiderations for module design and coding:
1N/A=head2 To OO or not to OO?
1N/AYour module may be object oriented (OO) or not, or it may have both kinds
1N/Aof interfaces available. There are pros and cons of each technique, which
1N/Ashould be considered when you design your API.
1N/AAccording to Damian Conway, you should consider using OO:
1N/AWhen the system is large or likely to become so
1N/AWhen the data is aggregated in obvious structures that will become objects
1N/AWhen the types of data form a natural hierarchy that can make use of inheritance
1N/AWhen operations on data vary according to data type (making
1N/Apolymorphic invocation of methods feasible)
1N/AWhen it is likely that new data types may be later introduced
1N/Ainto the system, and will need to be handled by existing code
1N/AWhen interactions between data are best represented by
1N/AWhen the implementation of system components is likely to
1N/Achange over time (and hence should be encapsulated)
1N/AWhen the system design is itself object-oriented
1N/AWhen large amounts of client code will use the software (and
1N/Ashould be insulated from changes in its implementation)
1N/AWhen many separate operations will need to be applied to the
1N/AThink carefully about whether OO is appropriate for your module.
1N/AGratuitous object orientation results in complex APIs which are
1N/Adifficult for the average module user to understand or use.
1N/A=head2 Designing your API
1N/AYour interfaces should be understandable by an average Perl programmer.
1N/AThe following guidelines may help you judge whether your API is
1N/Asufficiently straightforward:
1N/A=item Write simple routines to do simple things.
1N/AIt's better to have numerous simple routines than a few monolithic ones.
1N/AIf your routine changes its behaviour significantly based on its
1N/Aarguments, it's a sign that you should have two (or more) separate
1N/A=item Separate functionality from output.
1N/AReturn your results in the most generic form possible and allow the user
1N/Ato choose how to use them. The most generic form possible is usually a
1N/APerl data structure which can then be used to generate a text report,
1N/AHTML, XML, a database query, or whatever else your users require.
1N/AIf your routine iterates through some kind of list (such as a list of
1N/Afiles, or records in a database) you may consider providing a callback
1N/Aso that users can manipulate each element of the list in turn.
1N/AFile::Find provides an example of this with its
1N/AC<find(\&wanted, $dir)> syntax.
1N/A=item Provide sensible shortcuts and defaults.
1N/ADon't require every module user to jump through the same hoops to achieve a
1N/Asimple result. You can always include optional parameters or routines for
1N/Amore complex or non-standard behaviour. If most of your users have to
1N/Atype a few almost identical lines of code when they start using your
1N/Amodule, it's a sign that you should have made that behaviour a default.
1N/AAnother good indicator that you should use defaults is if most of your
1N/Ausers call your routines with the same arguments.
1N/A=item Naming conventions
1N/AYour naming should be consistent. For instance, it's better to have:
1N/AThis applies equally to method names, parameter names, and anything else
1N/Awhich is visible to the user (and most things that aren't!)
1N/A=item Parameter passing
1N/AUse named parameters. It's easier to use a hash like this:
1N/A... than to have a long list of unnamed parameters like this:
1N/A $obj->do_something("wibble", "text", 1024);
1N/AWhile the list of arguments might work fine for one, two or even three
1N/Aarguments, any more arguments become hard for the module user to
1N/Aremember, and hard for the module author to manage. If you want to add
1N/Aa new parameter you will have to add it to the end of the list for
1N/Abackward compatibility, and this will probably make your list order
1N/Aunintuitive. Also, if many elements may be undefined you may see the
1N/Afollowing unattractive method calls:
1N/A $obj->do_something(undef, undef, undef, undef, undef, undef, 1024);
1N/AProvide sensible defaults for parameters which have them. Don't make
1N/Ayour users specify parameters which will almost always be the same.
1N/AThe issue of whether to pass the arguments in a hash or a hashref is
1N/Alargely a matter of personal style.
1N/AThe use of hash keys starting with a hyphen (C<-name>) or entirely in
1N/Aupper case (C<NAME>) is a relic of older versions of Perl in which
1N/Aordinary lower case strings were not handled correctly by the C<=E<gt>>
1N/Aoperator. While some modules retain uppercase or hyphenated argument
1N/Akeys for historical reasons or as a matter of personal style, most new
1N/Amodules should use simple lower case keys. Whatever you choose, be
1N/A=head2 Strictness and warnings
1N/AYour module should run successfully under the strict pragma and should
1N/Arun without generating any warnings. Your module should also handle
1N/Ataint-checking where appropriate, though this can cause difficulties in
1N/A=head2 Backwards compatibility
1N/AModules which are "stable" should not break backwards compatibility
1N/Awithout at least a long transition phase and a major change in version
1N/A=head2 Error handling and messages
1N/AWhen your module encounters an error it should do one or more of:
1N/AReturn an undefined value.
1N/Aset C<$Module::errstr> or similar (C<errstr> is a common name used by
1N/ADBI and other popular modules; if you choose something else, be sure to
1N/Adocument it clearly).
1N/AC<warn()> or C<carp()> a message to STDERR.
1N/AC<croak()> only when your module absolutely cannot figure out what to
1N/Ado. (C<croak()> is a better version of C<die()> for use within
1N/Amodules, which reports its errors from the perspective of the caller.
1N/ASee L<Carp> for details of C<croak()>, C<carp()> and other useful
1N/AAs an alternative to the above, you may prefer to throw exceptions using
1N/AConfigurable error handling can be very useful to your users. Consider
1N/Aoffering a choice of levels for warning and debug messages, an option to
1N/Asend messages to a separate file, a way to specify an error-handling
1N/Aroutine, or other such features. Be sure to default all these options
1N/Ato the commonest use.
1N/A=head1 DOCUMENTING YOUR MODULE
1N/AYour module should include documentation aimed at Perl developers.
1N/AYou should use Perl's "plain old documentation" (POD) for your general
1N/Atechnical documentation, though you may wish to write additional
1N/Adocumentation (white papers, tutorials, etc) in some other format.
1N/AYou need to cover the following subjects:
1N/AA synopsis of the common uses of the module
1N/AThe purpose, scope and target applications of your module
1N/AUse of each publically accessible method or subroutine, including
1N/Aparameters and return values
1N/ASources of further information
1N/AThe level of detail in Perl module documentation generally goes from
1N/Aless detailed to more detailed. Your SYNOPSIS section should contain a
1N/Aminimal example of use (perhaps as little as one line of code; skip the
1N/Aunusual use cases or anything not needed by most users); the
1N/ADESCRIPTION should describe your module in broad terms, generally in
1N/Ajust a few paragraphs; more detail of the module's routines or methods,
1N/Alengthy code examples, or other in-depth material should be given in
1N/AIdeally, someone who's slightly familiar with your module should be able
1N/Ato refresh their memory without hitting "page down". As your reader
1N/Acontinues through the document, they should receive a progressively
1N/Agreater amount of knowledge.
1N/AThe recommended order of sections in Perl module documentation is:
1N/AOne or more sections or subsections giving greater detail of available
1N/Amethods and routines and any other relevant information.
1N/ACOPYRIGHT and LICENSE
1N/AKeep your documentation near the code it documents ("inline"
1N/Adocumentation). Include POD for a given method right above that
1N/Amethod's subroutine. This makes it easier to keep the documentation up
1N/Ato date, and avoids having to document each piece of code twice (once in
1N/APOD and once in comments).
1N/A=head2 README, INSTALL, release notes, changelogs
1N/AYour module should also include a README file describing the module and
1N/Agiving pointers to further information (website, author email).
1N/AAn INSTALL file should be included, and should contain simple installation
1N/Ainstructions. When using ExtUtils::MakeMaker this will usually be:
1N/AWhen using Module::Build, this will usually be:
1N/A=item perl Build test
1N/A=item perl Build install
1N/ARelease notes or changelogs should be produced for each release of your
1N/Asoftware describing user-visible changes to your module, in terms
1N/Arelevant to the user.
1N/A=head1 RELEASE CONSIDERATIONS
1N/A=head2 Version numbering
1N/AVersion numbers should indicate at least major and minor releases, and
1N/Apossibly sub-minor releases. A major release is one in which most of
1N/Athe functionality has changed, or in which major new functionality is
1N/Aadded. A minor release is one in which a small amount of functionality
1N/Ahas been added or changed. Sub-minor version numbers are usually used
1N/Afor changes which do not affect functionality, such as documentation
1N/AThe most common CPAN version numbering scheme looks like this:
1N/A 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
1N/AA correct CPAN version number is a floating point number with at least
1N/A2 digits after the decimal. You can test whether it conforms to CPAN by
1N/A perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' '
Foo.pm'
1N/AIf you want to release a 'beta' or 'alpha' version of a module but
1N/Adon't want
CPAN.pm to list it as most recent use an '_' after the
1N/Aregular version number followed by at least 2 digits, eg. 1.20_01. If
1N/Ayou do this, the following idiom is recommended:
1N/A $VERSION = "1.12_01";
1N/A $XS_VERSION = $VERSION; # only needed if you have XS code
1N/A $VERSION = eval $VERSION;
1N/AWith that trick MakeMaker will only read the first line and thus read
1N/Athe underscore, while the perl interpreter will evaluate the $VERSION
1N/Aand convert the string into a number. Later operations that treat
1N/A$VERSION as a number will then be able to do so without provoking a
1N/Awarning about $VERSION not being a number.
1N/ANever release anything (even a one-word documentation patch) without
1N/Aincrementing the number. Even a one-word documentation patch should
1N/Aresult in a change in version at the sub-minor level.
1N/A=head2 Pre-requisites
1N/AModule authors should carefully consider whether to rely on other
1N/Amodules, and which modules to rely on.
1N/AMost importantly, choose modules which are as stable as possible. In
1N/AUnstable CPAN modules
1N/AModules not available from CPAN
1N/ASpecify version requirements for other Perl modules in the
1N/ABuild.PL and with C<require 5.6.1> or similar. See the section on
1N/AAll modules should be tested before distribution (using "make disttest"),
1N/Aand the tests should also be available to people installing the modules
1N/AFor Module::Build you would use the C<make test> equivalent C<perl Build test>.
1N/AThe importance of these tests is proportional to the alleged stability of a
1N/Amodule -- a module which purports to be stable or which hopes to achieve wide
1N/Ause should adhere to as strict a testing regime as possible.
1N/AUseful modules to help you write tests (with minimum impact on your
1N/Adevelopment process or your time) include Test::Simple, Carp::Assert
1N/AFor more sophisticated test suites there are Test::More and Test::MockObject.
1N/AModules should be packaged using one of the standard packaging tools.
1N/ACurrently you have the choice between ExtUtils::MakeMaker and the
1N/Amore platform independent Module::Build, allowing modules to be installed in a
1N/AWhen using ExtUtils::MakeMaker, you can use "make dist" to create your
1N/Apackage. Tools exist to help you to build your module in a MakeMaker-friendly
1N/Astyle. These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
1N/AMake sure that your module has a license, and that the full text of it
1N/Ais included in the distribution (unless it's a common one and the terms
1N/Aof the license don't require you to include it).
1N/AIf you don't know what license to use, dual licensing under the GPL
1N/Aand Artistic licenses (the same as Perl itself) is a good idea.
1N/ASee L<perlgpl> and L<perlartistic>.
1N/A=head1 COMMON PITFALLS
1N/A=head2 Reinventing the wheel
1N/AThere are certain application spaces which are already very, very well
1N/Aserved by CPAN. One example is templating systems, another is date and
1N/Atime modules, and there are many more. While it is a rite of passage to
1N/Awrite your own version of these things, please consider carefully
1N/Awhether the Perl world really needs you to publish it.
1N/A=head2 Trying to do too much
1N/AYour module will be part of a developer's toolkit. It will not, in
1N/Aitself, form the B<entire> toolkit. It's tempting to add extra features
1N/Auntil your code is a monolithic system rather than a set of modular
1N/A=head2 Inappropriate documentation
1N/ADon't fall into the trap of writing for the wrong audience. Your
1N/Aprimary audience is a reasonably experienced developer with at least
1N/Aa moderate understanding of your module's application domain, who's just
1N/Adownloaded your module and wants to start using it as quickly as possible.
1N/ATutorials, end-user documentation, research papers, FAQs etc are not
1N/Aappropriate in a module's main documentation. If you really want to
1N/Awrite these, include them as sub-documents such as C<My::Module::Tutorial> or
1N/AC<My::Module::FAQ> and provide a link in the SEE ALSO section of the
1N/AGeneral Perl style guide
1N/AHow to create a new module
1N/AVerifies your POD's correctness
1N/A=item Packaging Tools
1N/AL<ExtUtils::MakeMaker>, L<Module::Build>
1N/AL<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
1N/APerl Authors Upload Server. Contains links to information for module
1N/A=item Any good book on software engineering
1N/AKirrily "Skud" Robert <skud@cpan.org>