Initial Commit

database/perl/lib/pods/perlmodstyle.pod

@@ -0,0 +1,813 @@
+=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<perlstyle> , 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<perlnewmod> 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<use strict> and C<-w>
+
+=item *
+
+Stable modules should maintain backwards compatibility
+
+=back
+
+=head2 Documentation
+
+=over 4
+
+=item *
+
+Write documentation in POD
+
+=item *
+
+Document purpose, scope and target applications
+
+=item *
+
+Document each publically accessible method or subroutine, including params and return values
+
+=item *
+
+Give examples of use in your documentation
+
+=item *
+
+Provide a README file and perhaps also release notes, changelog, etc
+
+=item *
+
+Provide links to further information (URL, email)
+
+=back
+
+=head2 Release considerations
+
+=over 4
+
+=item *
+
+Specify pre-requisites in Makefile.PL or Build.PL
+
+=item *
+
+Specify Perl version requirements with C<use>
+
+=item *
+
+Include tests with your module
+
+=item *
+
+Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)
+
+=item *
+
+Increment the version number for every change, no matter how small
+
+=item *
+
+Package the module using "make dist"
+
+=item *
+
+Choose an appropriate license (GPL/Artistic is a good default)
+
+=back
+
+=head1 BEFORE YOU START WRITING A MODULE
+
+Try not to launch headlong into developing your module without spending
+some time thinking first.  A little forethought may save you a vast
+amount of effort later on.
+
+=head2 Has it been done before?
+
+You may not even need to write the module.  Check whether it's already 
+been done in Perl, and avoid re-inventing the wheel unless you have a 
+good reason.
+
+Good places to look for pre-existing modules include
+L<MetaCPAN|https://metacpan.org> and L<PrePAN|http://prepan.org>
+and asking on C<module-authors@perl.org>
+(L<https://lists.perl.org/list/module-authors.html>).
+
+If an existing module B<almost> does what you want, consider writing a
+patch, writing a subclass, or otherwise extending the existing module
+rather than rewriting it.
+
+=head2 Do one thing and do it well
+
+At the risk of stating the obvious, modules are intended to be modular.
+A Perl developer should be able to use modules to put together the
+building blocks of their application.  However, it's important that the
+blocks are the right shape, and that the developer shouldn't have to use
+a big block when all they need is a small one.
+
+Your module should have a clearly defined scope which is no longer than
+a single sentence.  Can your module be broken down into a family of
+related modules?
+
+Bad example:
+
+"FooBar.pm provides an implementation of the FOO protocol and the
+related BAR standard."
+
+Good example:
+
+"Foo.pm provides an implementation of the FOO protocol.  Bar.pm
+implements the related BAR protocol."
+
+This means that if a developer only needs a module for the BAR standard,
+they should not be forced to install libraries for FOO as well.
+
+=head2 What's in a name?
+
+Make sure you choose an appropriate name for your module early on.  This
+will help people find and remember your module, and make programming
+with your module more intuitive.
+
+When naming your module, consider the following:
+
+=over 4
+
+=item *
+
+Be descriptive (i.e. accurately describes the purpose of the module).
+
+=item * 
+
+Be consistent with existing modules.
+
+=item *
+
+Reflect the functionality of the module, not the implementation.
+
+=item *
+
+Avoid starting a new top-level hierarchy, especially if a suitable
+hierarchy already exists under which you could place your module.
+
+=back
+
+=head2 Get feedback before publishing
+
+If you have never uploaded a module to CPAN before (and even if you have),
+you are strongly encouraged to get feedback on L<PrePAN|http://prepan.org>.
+PrePAN is a site dedicated to discussing ideas for CPAN modules with other
+Perl developers and is a great resource for new (and experienced) Perl
+developers.
+
+You should also try to get feedback from people who are already familiar
+with the module's application domain and the CPAN naming system.  Authors
+of similar modules, or modules with similar names, may be a good place to
+start, as are community sites like L<Perl Monks|https://www.perlmonks.org>.
+
+=head1 DESIGNING AND WRITING YOUR MODULE
+
+Considerations for module design and coding:
+
+=head2 To OO or not to OO?
+
+Your module may be object oriented (OO) or not, or it may have both kinds 
+of interfaces available.  There are pros and cons of each technique, which 
+should be considered when you design your API.
+
+In I<Perl Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
+Damian Conway provides a list of criteria to use when deciding if OO is the
+right fit for your problem:
+
+=over 4
+
+=item *
+
+The system being designed is large, or is likely to become large.
+
+=item *
+
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
+
+=item *
+
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
+
+=item *
+
+You have a piece of data on which many different operations are
+applied.
+
+=item *
+
+You need to perform the same general operations on related types of
+data, but with slight variations depending on the specific type of data
+the operations are applied to.
+
+=item *
+
+It's likely you'll have to add new data types later.
+
+=item *
+
+The typical interactions between pieces of data are best represented by
+operators.
+
+=item *
+
+The implementation of individual components of the system is likely to
+change over time.
+
+=item *
+
+The system design is already object-oriented.
+
+=item *
+
+Large numbers of other programmers will be using your code modules.
+
+=back
+
+Think carefully about whether OO is appropriate for your module.
+Gratuitous object orientation results in complex APIs which are
+difficult for the average module user to understand or use.
+
+=head2 Designing your API
+
+Your interfaces should be understandable by an average Perl programmer.  
+The following guidelines may help you judge whether your API is
+sufficiently straightforward:
+
+=over 4
+
+=item Write simple routines to do simple things.
+
+It's better to have numerous simple routines than a few monolithic ones.
+If your routine changes its behaviour significantly based on its
+arguments, it's a sign that you should have two (or more) separate
+routines.
+
+=item Separate functionality from output.  
+
+Return your results in the most generic form possible and allow the user 
+to choose how to use them.  The most generic form possible is usually a
+Perl data structure which can then be used to generate a text report,
+HTML, XML, a database query, or whatever else your users require.
+
+If your routine iterates through some kind of list (such as a list of
+files, or records in a database) you may consider providing a callback
+so that users can manipulate each element of the list in turn.
+File::Find provides an example of this with its 
+C<find(\&wanted, $dir)> syntax.
+
+=item Provide sensible shortcuts and defaults.
+
+Don't require every module user to jump through the same hoops to achieve a
+simple result.  You can always include optional parameters or routines for 
+more complex or non-standard behaviour.  If most of your users have to
+type a few almost identical lines of code when they start using your
+module, it's a sign that you should have made that behaviour a default.
+Another good indicator that you should use defaults is if most of your 
+users call your routines with the same arguments.
+
+=item Naming conventions
+
+Your naming should be consistent.  For instance, it's better to have:
+
+	display_day();
+	display_week();
+	display_year();
+
+than
+
+	display_day();
+	week_display();
+	show_year();
+
+This applies equally to method names, parameter names, and anything else
+which is visible to the user (and most things that aren't!)
+
+=item Parameter passing
+
+Use named parameters.  It's easier to use a hash like this:
+
+    $obj->do_something(
+	    name => "wibble",
+	    type => "text",
+	    size => 1024,
+    );
+
+... than to have a long list of unnamed parameters like this:
+
+    $obj->do_something("wibble", "text", 1024);
+
+While the list of arguments might work fine for one, two or even three
+arguments, any more arguments become hard for the module user to
+remember, and hard for the module author to manage.  If you want to add
+a new parameter you will have to add it to the end of the list for
+backward compatibility, and this will probably make your list order
+unintuitive.  Also, if many elements may be undefined you may see the
+following unattractive method calls:
+
+    $obj->do_something(undef, undef, undef, undef, undef, 1024);
+
+Provide sensible defaults for parameters which have them.  Don't make
+your users specify parameters which will almost always be the same.
+
+The issue of whether to pass the arguments in a hash or a hashref is
+largely a matter of personal style. 
+
+The use of hash keys starting with a hyphen (C<-name>) or entirely in 
+upper case (C<NAME>) is a relic of older versions of Perl in which
+ordinary lower case strings were not handled correctly by the C<=E<gt>>
+operator.  While some modules retain uppercase or hyphenated argument
+keys for historical reasons or as a matter of personal style, most new
+modules should use simple lower case keys.  Whatever you choose, be
+consistent!
+
+=back
+
+=head2 Strictness and warnings
+
+Your module should run successfully under the strict pragma and should
+run without generating any warnings.  Your module should also handle 
+taint-checking where appropriate, though this can cause difficulties in
+many cases.
+
+=head2 Backwards compatibility
+
+Modules which are "stable" should not break backwards compatibility
+without at least a long transition phase and a major change in version
+number.
+
+=head2 Error handling and messages
+
+When your module encounters an error it should do one or more of:
+
+=over 4
+
+=item *
+
+Return an undefined value.
+
+=item *
+
+set C<$Module::errstr> or similar (C<errstr> is a common name used by
+DBI and other popular modules; if you choose something else, be sure to
+document it clearly).
+
+=item *
+
+C<warn()> or C<carp()> a message to STDERR.  
+
+=item *
+
+C<croak()> only when your module absolutely cannot figure out what to
+do.  (C<croak()> is a better version of C<die()> for use within 
+modules, which reports its errors from the perspective of the caller.  
+See L<Carp> for details of C<croak()>, C<carp()> and other useful
+routines.)
+
+=item *
+
+As an alternative to the above, you may prefer to throw exceptions using 
+the Error module.
+
+=back
+
+Configurable error handling can be very useful to your users.  Consider
+offering a choice of levels for warning and debug messages, an option to
+send messages to a separate file, a way to specify an error-handling
+routine, or other such features.  Be sure to default all these options
+to the commonest use.
+
+=head1 DOCUMENTING YOUR MODULE
+
+=head2 POD
+
+Your module should include documentation aimed at Perl developers.
+You should use Perl's "plain old documentation" (POD) for your general 
+technical documentation, though you may wish to write additional
+documentation (white papers, tutorials, etc) in some other format.  
+You need to cover the following subjects:
+
+=over 4
+
+=item *
+
+A synopsis of the common uses of the module
+
+=item *
+
+The purpose, scope and target applications of your module
+
+=item *
+
+Use of each publically accessible method or subroutine, including
+parameters and return values
+
+=item *
+
+Examples of use
+
+=item *
+
+Sources of further information
+
+=item *
+
+A contact email address for the author/maintainer
+
+=back
+
+The level of detail in Perl module documentation generally goes from
+less detailed to more detailed.  Your SYNOPSIS section should contain a
+minimal example of use (perhaps as little as one line of code; skip the
+unusual use cases or anything not needed by most users); the
+DESCRIPTION should describe your module in broad terms, generally in
+just a few paragraphs; more detail of the module's routines or methods,
+lengthy code examples, or other in-depth material should be given in 
+subsequent sections.
+
+Ideally, someone who's slightly familiar with your module should be able
+to refresh their memory without hitting "page down".  As your reader
+continues through the document, they should receive a progressively
+greater amount of knowledge.
+
+The recommended order of sections in Perl module documentation is:
+
+=over 4
+
+=item * 
+
+NAME
+
+=item *
+
+SYNOPSIS
+
+=item *
+
+DESCRIPTION
+
+=item *
+
+One or more sections or subsections giving greater detail of available 
+methods and routines and any other relevant information.
+
+=item *
+
+BUGS/CAVEATS/etc
+
+=item *
+
+AUTHOR
+
+=item *
+
+SEE ALSO
+
+=item *
+
+COPYRIGHT and LICENSE
+
+=back
+
+Keep your documentation near the code it documents ("inline"
+documentation).  Include POD for a given method right above that 
+method's subroutine.  This makes it easier to keep the documentation up
+to date, and avoids having to document each piece of code twice (once in
+POD and once in comments).
+
+=head2 README, INSTALL, release notes, changelogs
+
+Your module should also include a README file describing the module and
+giving pointers to further information (website, author email).  
+
+An INSTALL file should be included, and should contain simple installation 
+instructions.  When using ExtUtils::MakeMaker this will usually be:
+
+=over 4
+
+=item perl Makefile.PL
+
+=item make
+
+=item make test
+
+=item make install
+
+=back
+
+When using Module::Build, this will usually be:
+
+=over 4
+
+=item perl Build.PL
+
+=item perl Build
+
+=item perl Build test
+
+=item perl Build install
+
+=back
+
+Release notes or changelogs should be produced for each release of your
+software describing user-visible changes to your module, in terms
+relevant to the user.
+
+Unless you have good reasons for using some other format
+(for example, a format used within your company),
+the convention is to name your changelog file C<Changes>,
+and to follow the simple format described in L<CPAN::Changes::Spec>.
+
+=head1 RELEASE CONSIDERATIONS
+
+=head2 Version numbering
+
+Version numbers should indicate at least major and minor releases, and
+possibly sub-minor releases.  A major release is one in which most of
+the functionality has changed, or in which major new functionality is
+added.  A minor release is one in which a small amount of functionality
+has been added or changed.  Sub-minor version numbers are usually used
+for changes which do not affect functionality, such as documentation
+patches.
+
+The most common CPAN version numbering scheme looks like this:
+
+    1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
+
+A correct CPAN version number is a floating point number with at least 
+2 digits after the decimal.  You can test whether it conforms to CPAN by 
+using
+
+    perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' \
+                                                            'Foo.pm'
+
+If you want to release a 'beta' or 'alpha' version of a module but
+don't want CPAN.pm to list it as most recent use an '_' after the
+regular version number followed by at least 2 digits, eg. 1.20_01.  If
+you do this, the following idiom is recommended:
+
+  our $VERSION = "1.12_01"; # so CPAN distribution will have
+                            # right filename
+  our $XS_VERSION = $VERSION; # only needed if you have XS code
+  $VERSION = eval $VERSION; # so "use Module 0.002" won't warn on
+                            # underscore
+
+With that trick MakeMaker will only read the first line and thus read
+the underscore, while the perl interpreter will evaluate the $VERSION
+and convert the string into a number.  Later operations that treat
+$VERSION as a number will then be able to do so without provoking a
+warning about $VERSION not being a number.
+
+Never release anything (even a one-word documentation patch) without
+incrementing the number.  Even a one-word documentation patch should
+result in a change in version at the sub-minor level.
+
+Once picked, it is important to stick to your version scheme, without
+reducing the number of digits.  This is because "downstream" packagers,
+such as the FreeBSD ports system, interpret the version numbers in
+various ways.  If you change the number of digits in your version scheme,
+you can confuse these systems so they get the versions of your module
+out of order, which is obviously bad.
+
+=head2 Pre-requisites
+
+Module authors should carefully consider whether to rely on other
+modules, and which modules to rely on.
+
+Most importantly, choose modules which are as stable as possible.  In
+order of preference: 
+
+=over 4
+
+=item *
+
+Core Perl modules
+
+=item *
+
+Stable CPAN modules
+
+=item *
+
+Unstable CPAN modules
+
+=item *
+
+Modules not available from CPAN
+
+=back
+
+Specify version requirements for other Perl modules in the
+pre-requisites in your Makefile.PL or Build.PL.
+
+Be sure to specify Perl version requirements both in Makefile.PL or
+Build.PL and with C<require 5.6.1> or similar.  See the section on
+C<use VERSION> of L<perlfunc/require> for details.
+
+=head2 Testing
+
+All modules should be tested before distribution (using "make disttest"),
+and the tests should also be available to people installing the modules 
+(using "make test").  
+For Module::Build you would use the C<make test> equivalent C<perl Build test>.
+
+The importance of these tests is proportional to the alleged stability of a 
+module.  A module which purports to be
+stable or which hopes to achieve wide 
+use should adhere to as strict a testing regime as possible.
+
+Useful modules to help you write tests (with minimum impact on your 
+development process or your time) include Test::Simple, Carp::Assert 
+and Test::Inline.
+For more sophisticated test suites there are Test::More and Test::MockObject.
+
+=head2 Packaging
+
+Modules should be packaged using one of the standard packaging tools.
+Currently you have the choice between ExtUtils::MakeMaker and the
+more platform independent Module::Build, allowing modules to be installed in a
+consistent manner.
+When using ExtUtils::MakeMaker, you can use "make dist" to create your
+package.  Tools exist to help you to build your module in a
+MakeMaker-friendly style.  These include ExtUtils::ModuleMaker and h2xs.
+See also L<perlnewmod>.
+
+=head2 Licensing
+
+Make sure that your module has a license, and that the full text of it
+is included in the distribution (unless it's a common one and the terms
+of the license don't require you to include it).
+
+If you don't know what license to use, dual licensing under the GPL
+and Artistic licenses (the same as Perl itself) is a good idea.
+See L<perlgpl> and L<perlartistic>.
+
+=head1 COMMON PITFALLS
+
+=head2 Reinventing the wheel
+
+There are certain application spaces which are already very, very well
+served by CPAN.  One example is templating systems, another is date and
+time modules, and there are many more.  While it is a rite of passage to
+write your own version of these things, please consider carefully
+whether the Perl world really needs you to publish it.
+
+=head2 Trying to do too much
+
+Your module will be part of a developer's toolkit.  It will not, in
+itself, form the B<entire> toolkit.  It's tempting to add extra features
+until your code is a monolithic system rather than a set of modular
+building blocks.
+
+=head2 Inappropriate documentation
+
+Don't fall into the trap of writing for the wrong audience.  Your
+primary audience is a reasonably experienced developer with at least 
+a moderate understanding of your module's application domain, who's just 
+downloaded your module and wants to start using it as quickly as possible.
+
+Tutorials, end-user documentation, research papers, FAQs etc are not 
+appropriate in a module's main documentation.  If you really want to 
+write these, include them as sub-documents such as C<My::Module::Tutorial> or
+C<My::Module::FAQ> and provide a link in the SEE ALSO section of the
+main documentation.  
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<perlstyle>
+
+General Perl style guide
+
+=item L<perlnewmod>
+
+How to create a new module
+
+=item L<perlpod>
+
+POD documentation
+
+=item L<podchecker>
+
+Verifies your POD's correctness
+
+=item Packaging Tools
+
+L<ExtUtils::MakeMaker>, L<Module::Build>
+
+=item Testing tools
+
+L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
+
+=item L<https://pause.perl.org/>
+
+Perl Authors Upload Server.  Contains links to information for module
+authors.
+
+=item Any good book on software engineering
+
+=back
+
+=head1 AUTHOR
+
+Kirrily "Skud" Robert <skud@cpan.org>
+