CONVENTIONS

=head1 Biome Conventions and Best Practices

=head2 Last updated July 29, 2009

This is a short style guide for Biome. In general, consult Perl Best Practices:

http://refcards.com/docs/vromansj/perl-best-practices/refguide.pdf

or Moose Best Practices:

http://search.cpan.org/perldoc?Moose::Manual::BestPractices

=head1 Perl version

At the moment we are requiring a minimum of perl 5.10.0 and Modern::Perl; perl
5.10.1 is highly recommended, as it fixes a significant memory leak with
Scalar::Util::weaken(). We also recommend all warnings and strictures, and fully
expect that features present in 5.10.1 will be used (smart matching, state
variables, given/when, defined-or, etc).

We may migrate to a perl 5.12.0 minimal requirement, or just allow the use of
5.12 features for specific modules.  In general, take advantage of several key
features for that release, including pluggable keywords, module version syntax,
better switch statements and smart matching, parallel tests, default 'use
strict', and so on. 

=head1 Moose and MooseX

We are currently requiring at least Moose 1.01, but it is safest to use the
latest release. As for MooseX modules, some of what we are using:

    MooseX::Types
    MooseX::ClassAttributes
    MooseX::Role::Parameterized
    MooseX::Aliases
    
Others may be added along the way. MooseX::AttributeHelpers has been moved into
the Moose core, therefore at that point we will remove that module as a
dependency and bump the required Moose core version.

For the time being, we will not be using MooseX::Declare or
MooseX::Method::Signatures. This is primarily based on three concerns:

  * Performance - Using MooseX::Declare and/or MooseX::Method::Signatures has
    been reported to cause a fairly decent performance hit. However, this
    needs to be substantiated within this framework.
  
  * Stability - MooseX::Method::Signatures works best with MooseX::Declare, but
    both are still considered to be alpha software.
    
  * Dependencies - the dependency tree for both modules is quite extensive.

If demonstrated that usage of either module isn't detrimental to overall
performance (a major concern with this project), then we may revisit this at a
later time.

An additional concern (though we allow it for now) is the use of MooseX::Types.
We are allowing it for the time being, but if it is decided that there is a
significant performance hit for it's use, we may revert to using simple core
Moose types.

=head1 Documentation

The best source for an overall picture of how to document code is the
'Documentation' chapter of PBP.  In general...

  * All modules should eventually contain a BioPerl-style boiler-plate set of
    docs, including NAME, SYNOPSIS, DESCRIPTION, AUTHOR. Optional sections may
    be VERSION, DEPENDENCIES, CONFIGURATION/ENVIRONMENT, INCOMPATIBILITIES,
    BUGS/LIMITATIONS, etc.
    
  * All POD should be placed in one place, preferably at the end of the file
    after the __END__ directives

=head1 Attributes

Attributes should be typed where possible (with 'isa' or 'does'). Subtypes
should go into the Biome::Type namespace (use a namespace for the specific data
type), for now using MooseX::Types, and should be exported.

=head1 Roles

For the time being Roles in Biome can be either fully implemented, completely
abstract, or both. They may also be parametric (see Bio::Role::Annotate for a
simple example using MooseX::Role::Parameterized).

=head2 Role names

Currently, there is no real convention for naming roles in Biome. We currently
have a mismach of conventions, actually. However, I (cjfields) propose the
following rules. If these are generally agreed upon, we will start migrating
their namespaces appropriately.

=over 3

=item * Simple behavior/action-based roles

A role that performs a simple behavior or action is simply named after it's
action or behavior (Biome::Role::Annotate). If it represents a collection
behavior, possibly use '*able' (Biome::Role::Annotatable, a collection of
instances that do Biome::Role::Annotate).

=item * Anything that simply delegates to a 

=back

=head1 Classes

As mentioned above, we are flattening much of the class hierarchy using roles
where applicable. There are obvious caveats to that. Roles may not make the most
sense in some cases; delegation or inheritance may be completely valid options
from a design point-of-view.

=head1 Mutability

There are good arguments for and against object mutability. BioPerl actually
practices a sort of limited mutability, in that you can get/set attributes in
most cases, but usage of some methods (subseq, for instance) returns a new
instance of the class with modified attributes.

With Biome we may go with the assumption that, once an object is instantiated,
it is essentially validated, and that any validation occurs lazily. Classes can
still define a specific validation method for doing something like checking data
types (seq alphabet, etc)