|
|
package Sipwise::CodingStandards;
|
|
|
use Sipwise::Base;
|
|
|
our $VERSION = '1.000';
|
|
|
|
|
|
__END__
|
|
|
|
|
|
=encoding UTF-8
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
|
Sipwise::CodingStandards - Sipwise Perl coding standards
|
|
|
|
|
|
=head1 VERSION
|
|
|
|
|
|
This document describes Sipwise::CodingStandards version 1.000
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
This document outlines the coding standards for new Perl projects. Their purpose is to guide programmers to a common
|
|
|
code style and practices, making decisions so you don't have to. Follow them unless you have a good reason not to. See
|
|
|
L<http://oreilly.com/catalog/perlbp/|chapter 1 in PBP> for the rationale. Taking Perl's philosophy to heart, the
|
|
|
standards are not enforced – it's up to the programmer to use common sense and sound judgement in applying them.
|
|
|
|
|
|
The standards are not set in stone, either. If you notice that consistently I<not> following them produces better
|
|
|
results, please communicate the matter and get this document ameliorated.
|
|
|
|
|
|
=head2 common modules
|
|
|
|
|
|
L<Sipwise::Base> is a module that simply bundles common other modules that you are very likely to include in a class
|
|
|
file - one line is enough to load all of them. The goal is to enable modern Perl programming and restrict some legacy
|
|
|
features of the language that should not be used anymore in new code.
|
|
|
|
|
|
=head2 versions
|
|
|
|
|
|
=head3 examples
|
|
|
|
|
|
our $VERSION = '2.001'; # 2nd version of revision 2
|
|
|
our $VERSION = '2.420'; # 421st version of revision 2
|
|
|
|
|
|
=head3 rationale
|
|
|
|
|
|
Every module must have a version or else it is problematic to accurately specify a dependency when a distribution is
|
|
|
split. It works best when the distribution version and each module's version are equal and increased in lock-step. To
|
|
|
to make this easy, use C<perl-reversion>, which is part of L<Perl::Version>. Increase a version each time when you need
|
|
|
to depend on a new features or a changed API from code external to the distribution, it should be followed by a release
|
|
|
of the distribution.
|
|
|
|
|
|
A version is a string consisting of a revision number, a literal dot as separator and a version number, altogether in
|
|
|
the form C<y.xxx>. C<y> is a natural number, C<xxx> are exactly three zero-padded digits. String quoting prevents
|
|
|
trailing zeroes from disappearing. Padding to the same amount of digits prevents confusion about C<< 1.10 < 1.9 >>.
|
|
|
Having exactly one separator prevents confusion about C<5.10.1 == 5.010001>.
|
|
|
|
|
|
Do not use the L<version> module for declaring versions. Using plain strings prevents that ugly C<v> prefix in a
|
|
|
distribution tarball name. However, using the module to handle versions, e.g. for comparing them, is a good idea.
|
|
|
|
|
|
Do not use L<v-strings|http://p3rl.org/data#Version-Strings>. They are poorly understood.
|
|
|
|
|
|
Do not use underscores. Using underscores require to L<eval> the version to turn it into a number. If you want to mark
|
|
|
a distribution as release candidate to the PAUSE indexer, add the word C<TRIAL> to the distribution name, see
|
|
|
L<http://pause.perl.org/pause/query?ACTION=pause_04about#developerreleases>.
|
|
|
|
|
|
=head3 compliance
|
|
|
|
|
|
This scheme is fully compatible with the advice laid out in L<perlmodstyle>, L<version>,
|
|
|
L<"strict" version rules|http://p3rl.org/perl5120delta#Version-number-formats>,
|
|
|
L<"Version numbers should be boring"|http://www.dagolden.com/index.php/369/>,
|
|
|
L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitVersionStrings>,
|
|
|
L<Perl::Critic::Policy::ValuesAndExpressions::RequireNumericVersion>.
|
|
|
|
|
|
It is incompatible with L<semver|http://semver.org>.
|
|
|
|
|
|
=head2 sample code template
|
|
|
|
|
|
See L<Sipwise::Boilerplate> in this distribution.
|
|
|
|
|
|
This template is derived from L<Module::Starter::PBP> for the most part.
|
|
|
|
|
|
=head2 C<perltidy>
|
|
|
|
|
|
See F<share/.perltidyrc> in this distribution.
|
|
|
|
|
|
L<perltidy> sometimes produces not optimal results with immediately nested pairs of types of brackets.
|
|
|
|
|
|
$resultset->find({
|
|
|
foo => 123,
|
|
|
},
|
|
|
{
|
|
|
bar_id => 23,
|
|
|
quux_id => {-ident => 'baz_id'},
|
|
|
},
|
|
|
);
|
|
|
|
|
|
It is okay to manually fix this for symmetry.
|
|
|
|
|
|
$resultset->find(
|
|
|
{
|
|
|
foo => 123,
|
|
|
},
|
|
|
{
|
|
|
bar_id => 23,
|
|
|
quux_id => {-ident => 'baz_id'},
|
|
|
},
|
|
|
);
|
|
|
|
|
|
=head2 C<perlcritic>
|
|
|
|
|
|
See F<share/.perlcritic> in this distribution.
|
|
|
|
|
|
Install L<Task::Perl::Critic::IncludingOptionalDependencies> and L<Perl::Critic::logicLAB>.
|
|
|
|
|
|
=head1 AUTHOR
|
|
|
|
|
|
C<< <ldieckow@sipwise.com> >>
|
