=item *
-Specify pre-requisites in Makefile.PL
+Specify pre-requisites in Makefile.PL or Build.PL
=item *
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
+http://search.cpan.org/ and asking on modules@perl.org
+
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.
of interfaces available. There are pros and cons of each technique, which
should be considered when you design your API.
-According to Damian Conway, you should consider using OO:
+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 *
+=item *
-When the system is large or likely to become so
+The system being designed is large, or is likely to become large.
-=item *
+=item *
-When the data is aggregated in obvious structures that will become objects
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
-=item *
+=item *
-When the types of data form a natural hierarchy that can make use of inheritance
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
=item *
-When operations on data vary according to data type (making
-polymorphic invocation of methods feasible)
+You have a piece of data on which many different operations are
+applied.
=item *
-When it is likely that new data types may be later introduced
-into the system, and will need to be handled by existing code
+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 *
-When interactions between data are best represented by
-overloaded operators
+It's likely you'll have to add new data types later.
=item *
-When the implementation of system components is likely to
-change over time (and hence should be encapsulated)
+The typical interactions between pieces of data are best represented by
+operators.
=item *
-When the system design is itself object-oriented
+The implementation of individual components of the system is likely to
+change over time.
=item *
-When large amounts of client code will use the software (and
-should be insulated from changes in its implementation)
+The system design is already object-oriented.
=item *
-When many separate operations will need to be applied to the
-same set of data
+Large numbers of other programmers will be using your code modules.
=back
giving pointers to further information (website, author email).
An INSTALL file should be included, and should contain simple installation
-instructions (usually "perl Makefile.PL; make; make install").
+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
=back
Specify version requirements for other Perl modules in the
-pre-requisites in your Makefile.PL.
+pre-requisites in your Makefile.PL or Build.PL.
-Be sure to specify Perl version requirements both in Makefile.PL and
-with C<require 5.6.1> or similar.
+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",
+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
+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 the standard MakeMaker tools, allowing
-them to be installed in a consistent manner. Use "make dist" to create
-your package.
-
-Tools exist to help you build your module in a MakeMaker-friendly style.
-These include ExtUtils::ModuleMaker and h2xs. See also L<perlnewmod>.
+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
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
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::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject>
=item http://pause.perl.org/
https://perl5.git.perl.org / perl5.git / blobdiff