Of course, as with any list of "best practices", these are really just
opinions. Feel free to ignore us.
-=head2 "No Moose" and Immutabilize
+=head2 C<no Moose> and immutabilize
We recommend that you end your Moose class definitions by removing the
Moose sugar and making your class immutable.
1;
-The C<no Moose> bit is simply good code hygiene, and making classes
-immutable speeds up a lot of things, most notably object construction.
+The C<no Moose> bit simply good code hygiene, as it removes all the
+Moose keywords that are no longer needed once your class has been
+built. C<make_immutable> relinquishes your right to make further
+changes to your class, and allows Moose to speed up a lot of things,
+most notably object construction.
-=head2 Always call SUPER::BUILDARGS
+=head2 Never override C<new>
+
+Overriding C<new> is a very bad practice. Instead, you should use a
+C<BUILD> or C<BUILDARGS> methods to do the same thing. When you
+override C<new>, Moose can no longer inline a constructor when your
+class is immutabilized.
+
+There are two good reasons to override C<new>. One, you are writing a
+MooseX extension that provides its own L<Moose::Object> subclass
+I<and> a subclass of L<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
+;)
+
+=head2 Always call C<SUPER::BUILDARGS>
If you override the C<BUILDARGS> method in your class, make sure to
play nice and call C<SUPER::BUILDARGS> to handle cases you're not
list and hashref of named parameters correctly, and also checks for a
I<non-hashref> single argument.
-=head2 Don't Use the C<initializer> Feature
+=head2 Provide defaults whenever possible, otherwise use C<required>
-Don't know what we're talking about? That's fine.
+When your class provides defaults, this makes constructing new objects
+simpler. If you cannot provide a default, consider making the
+attribute C<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.
-=head2 Use C<builder> Instead of C<default> Most of the Time.
+=head2 Use C<builder> instead of C<default> most of the time
Builders can be inherited, they have explicit names, and they're just
plain cleaner.
going to be lazy, use I<lazy_build> to save yourself some typing and
standardize names.
-=head2 Consider Keeping Clearers and Predicates Private
+=head2 Consider keeping clearers and predicates private
Does everyone I<really> need to be able to clear an attribute?
Probably not. Don't expose this functionality outside your class
Predicates are less problematic, but there's no reason to make your
public API bigger than it has to be.
-=head2 Default to read-only, and Consider Keeping Writers Private
+=head2 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
writer a separate private method. Narrower APIs are easy to maintain,
and mutable state is trouble.
-=head2 Think Twice Before Changing an Attribute's Type in a Subclass
+=head2 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.
-=head2 Use L<MooseX::AttributeHelpers> Instead of C<auto_deref>
+=head2 Don't use the C<initializer> feature
+
+Don't know what we're talking about? That's fine.
+
+=head2 Use L<MooseX::AttributeHelpers> instead of C<auto_deref>
The C<auto_deref> feature is a bit troublesome. Directly exposing a
complex attribute is ugly. Instead, consider using
of functionality that need exposing. Then you can expose just the
functionality that you want.
-=head2 Namespace Your Types
+=head2 Always call C<inner> in the most specific subclass
+
+When using C<augment> and C<inner>, we recommend that you call
+C<inner> in the most specific subclass of your hierarchy. This makes
+it possible to subclass further and extend the hierarchy without
+changing the parents.
+
+=head2 Namespace your types
Use some sort of namespacing convention for type names. We recommend
-something like "MyApp.Type.Foo". I<Never> use "::" as the namespace
-separator, since that overlaps with actual class names.
+something like "MyApp::Type::Foo".
+
+If you're intending to package your types up for re-use using
+L<MooseX::Types> later, avoid using characters that are invalid in
+perl identifiers such as a space or period.
+
+=head2 Do not coerce Moose built-ins directly
+
+If you define a coercion for a Moose built-in like C<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:
-=head2 Coercion Instead of Unions
+ subtype 'My::ArrayRef' => as 'ArrayRef';
+
+ coerce 'My::ArrayRef'
+ => from 'Str'
+ => via { [ split /,/ ] };
+
+=head2 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( %{$_} ) };
+
+=head2 Use coercion instead of unions
Consider using a type coercion instead of a type union. This was
covered at length in L<Moose::Manual::Types>.
-=head2 Define All Your Types in One Module
+=head2 Define all your types in one module
Define all your types and coercions in one module. This was also
covered in L<Moose::Manual::Types>.
+=head1 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 C<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.
+
=head1 AUTHOR
+Yuval (nothingmuch) Kogman
+
Dave Rolsky E<lt>autarch@urth.orgE<gt>
=head1 COPYRIGHT AND LICENSE
projects / gitmo/Moose.git / blobdiff