package Sipwise::CodingStandards 1.004;
use Sipwise::Base;

__END__

=encoding UTF-8

=head1 NAME

Sipwise::CodingStandards - Sipwise Perl coding standards

=head1 VERSION

This document describes Sipwise::CodingStandards version 1.004

=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<< chapter 1 in I<PBP>|http://oreilly.com/catalog/perlbp/ >> 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

For modules:

    package Foo::Bar 2.001; # 2nd version of revision 2
    package Fnord 2.420;    # 421st version of revision 2

Otherwise:

    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.

When using the L<perlfunc/package> declaration, a version is a rational number. If a C<package> declaration is not
suitable, declare the magic C<$VERSION> variable (see L<perlobj/VERSION($need)>) and then a version is a string.

In any case, the version consists 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<perlfunc/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<< I<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 OK 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> >>