NAME

       Moose::Manual::BestPractices - Get the most out of Moose

VERSION

       version 2.2009

RECOMMENDATIONS

       Moose has a lot of features, and there's definitely more than one way to do it. However,
       we think that picking a subset of these features and using them consistently makes
       everyone's life easier.

       Of course, as with any list of "best practices", these are really just opinions. Feel free
       to ignore us.

   "namespace::autoclean" and immutabilize
       We recommend that you remove the Moose sugar and end your Moose class definitions by
       making your class immutable.

         package Person;

         use Moose;
         use namespace::autoclean;

         # extends, roles, attributes, etc.

         # methods

         __PACKAGE__->meta->make_immutable;

         1;

       The "use namespace::autoclean" bit is simply good code hygiene, as it removes imported
       symbols from your class's namespace at the end of your package's compile cycle, including
       Moose keywords.  Once the class has been built, these keywords are not needed. (This is
       preferred to placing "no Moose" at the end of your package).

       The "make_immutable" call allows Moose to speed up a lot of things, most notably object
       construction. The trade-off is that you can no longer change the class definition.

   Never override "new"
       Overriding "new" is a very bad practice. Instead, you should use a "BUILD" or "BUILDARGS"
       methods to do the same thing. When you override "new", Moose can no longer inline a
       constructor when your class is immutabilized.

       There are two good reasons to override "new". One, you are writing a MooseX extension that
       provides its own Moose::Object subclass and a subclass of Moose::Meta::Method::Constructor
       to inline the constructor. Two, you are subclassing a non-Moose parent.

       If you know how to do that, you know when to ignore this best practice ;)

   Always call the original/parent "BUILDARGS"
       If you "override" the "BUILDARGS" method in your class, make sure to play nice and call
       "super()" to handle cases you're not checking for explicitly.

       The default "BUILDARGS" method in Moose::Object handles both a list and hashref of named
       parameters correctly, and also checks for a non-hashref single argument.

   Provide defaults whenever possible, otherwise use "required"
       When your class provides defaults, this makes constructing new objects simpler. If you
       cannot provide a default, consider making the attribute "required".

       If you don't do either, an attribute can simply be left unset, increasing the complexity
       of your object, because it has more possible states that you or the user of your class
       must account for.

   Use "builder" instead of "default" most of the time
       Builders can be inherited, they have explicit names, and they're just plain cleaner.

       However, do use a default when the default is a non-reference, or when the default is
       simply an empty reference of some sort.

       Also, keep your builder methods private.

   Be "lazy"
       Lazy is good, and often solves initialization ordering problems. It's also good for
       deferring work that may never have to be done. Make your attributes "lazy" unless they're
       "required" or have trivial defaults.

   Consider keeping clearers and predicates private
       Does everyone really need to be able to clear an attribute?  Probably not. Don't expose
       this functionality outside your class by default.

       Predicates are less problematic, but there's no reason to make your public API bigger than
       it has to be.

   Avoid "lazy_build"
       As described above, you rarely actually need a clearer or a predicate.  "lazy_build" adds
       both to your public API, which exposes you to use cases that you must now test for. It's
       much better to avoid adding them until you really need them - use explicit "lazy" and
       "builder" options instead.

   Default to read-only, and consider keeping writers private
       Making attributes mutable just means more complexity to account for in your program. The
       alternative to mutable state is to encourage users of your class to simply make new
       objects as needed.

       If you must make an attribute read-write, consider making the writer a separate private
       method. Narrower APIs are easy to maintain, and mutable state is trouble.

       In order to declare such attributes, provide a private "writer" parameter:

           has pizza => (
               is     => 'ro',
               isa    => 'Pizza',
               writer => '_pizza',
           );

   Think twice before changing an attribute's type in a subclass
       Down this path lies great confusion. If the attribute is an object itself, at least make
       sure that it has the same interface as the type of object in the parent class.

   Don't use the "initializer" feature
       Don't know what we're talking about? That's fine.

   Use Moose::Meta::Attribute::Native traits instead of "auto_deref"
       The "auto_deref" feature is a bit troublesome. Directly exposing a complex attribute is
       ugly. Instead, consider using Moose::Meta::Attribute::Native traits to define an API that
       only exposes the necessary pieces of functionality.

   Always call "inner" in the most specific subclass
       When using "augment" and "inner", we recommend that you call "inner" in the most specific
       subclass of your hierarchy. This makes it possible to subclass further and extend the
       hierarchy without changing the parents.

   Namespace your types
       Use some sort of namespacing convention for type names. We recommend something like
       "MyApp::Type::Foo". We also recommend considering MooseX::Types.

   Do not coerce Moose built-ins directly
       If you define a coercion for a Moose built-in like "ArrayRef", this will affect every
       application in the Perl interpreter that uses this type.

           # very naughty!
           coerce 'ArrayRef'
               => from Str
               => via { [ split /,/ ] };

       Instead, create a subtype and coerce that:

           subtype 'My::ArrayRef' => as 'ArrayRef';

           coerce 'My::ArrayRef'
               => from 'Str'
               => via { [ split /,/ ] };

   Do not coerce class names directly
       Just as with Moose built-in types, a class type is global for the entire interpreter. If
       you add a coercion for that class name, it can have magical side effects elsewhere:

           # also very naughty!
           coerce 'HTTP::Headers'
               => from 'HashRef'
               => via { HTTP::Headers->new( %{$_} ) };

       Instead, we can create an "empty" subtype for the coercion:

           subtype 'My::HTTP::Headers' => as class_type('HTTP::Headers');

           coerce 'My::HTTP::Headers'
               => from 'HashRef'
               => via { HTTP::Headers->new( %{$_} ) };

   Use coercion instead of unions
       Consider using a type coercion instead of a type union. This was covered in
       Moose::Manual::Types.

   Define all your types in one module
       Define all your types and coercions in one module. This was also covered in
       Moose::Manual::Types.

BENEFITS OF BEST PRACTICES

       Following these practices has a number of benefits.

       It helps ensure that your code will play nice with others, making it more reusable and
       easier to extend.

       Following an accepted set of idioms will make maintenance easier, especially when someone
       else has to maintain your code. It will also make it easier to get support from other
       Moose users, since your code will be easier to digest quickly.

       Some of these practices are designed to help Moose do the right thing, especially when it
       comes to immutabilization. This means your code will be faster when immutabilized.

       Many of these practices also help get the most out of meta programming. If you used an
       overridden "new" to do type coercion by hand, rather than defining a real coercion, there
       is no introspectable metadata. This sort of thing is particularly problematic for MooseX
       extensions which rely on introspection to do the right thing.

AUTHORS

       •   Stevan Little <stevan.little@iinteractive.com>

       •   Dave Rolsky <autarch@urth.org>

       •   Jesse Luehrs <doy@tozt.net>

       •   Shawn M Moore <code@sartak.org>

       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>

       •   Karen Etheridge <ether@cpan.org>

       •   Florian Ragwitz <rafl@debian.org>

       •   Hans Dieter Pearcey <hdp@weftsoar.net>

       •   Chris Prather <chris@prather.org>

       •   Matt S Trout <mst@shadowcat.co.uk>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2006 by Infinity Interactive, Inc.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.