-=pod
+package Moose::Manual::BestPractices;
+
+# ABSTRACT: Get the most out of Moose
-=head1 NAME
+__END__
-Moose::Manual::BestPractices - Get the most out of Moose
+=pod
=head1 RECOMMENDATIONS
=head2 C<namespace::autoclean> and immutabilize
-We recommend that you remove the Moose sugar and end your Moose class
+We recommend that you remove the Moose sugar and end your Moose class
definitions by making your class immutable.
package Person;
The C<use namespace::autoclean> bit is simply good code hygiene, as it removes
imported symbols from you 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 needed. The C<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.
+built, these keywords are not needed.
-C<no Moose;> may be used to unimport only Moose's imported symbols.
-L<namespace::clean> provides finer-grained control than L<namespace::autoclean>.
+The C<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.
=head2 Never override C<new>
If you know how to do that, you know when to ignore this best practice
;)
-=head2 Always call C<SUPER::BUILDARGS>
+=head2 Always call the original/parent C<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
-checking for explicitly.
+If you C<override> the C<BUILDARGS> method in your class, make sure to play
+nice and call C<super()> to handle cases you're not checking for explicitly.
The default C<BUILDARGS> method in L<Moose::Object> handles both a
list and hashref of named parameters correctly, and also checks for a
Also, keep your builder methods private.
-=head2 Use C<lazy_build>
+=head2 Be C<lazy>
-Lazy is good, and often solves initialization ordering problems. It's
-also good for deferring work that may never have to be done. If you're
-going to be lazy, use C<lazy_build> to save yourself some typing and
-standardize names.
+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
+C<lazy> unless they're C<required> or have trivial defaults.
=head2 Consider keeping clearers and predicates private
=head2 Use L<Moose::Meta::Attribute::Native> traits instead of C<auto_deref>
-The C<auto_deref> feature is a bit troublesome. Directly exposing a
-complex attribute is ugly. Instead, consider using
-L<Moose::Meta::Attribute::Native> traits to define an API that exposes only
-necessary pieces of functionality.
+The C<auto_deref> feature is a bit troublesome. Directly exposing a complex
+attribute is ugly. Instead, consider using L<Moose::Meta::Attribute::Native>
+traits to define an API that only exposes the necessary pieces of
+functionality.
=head2 Always call C<inner> in the most specific subclass
=head2 Namespace your types
-Use some sort of namespacing convention for type names. We recommend
-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.
+Use some sort of namespacing convention for type names. We recommend something
+like "MyApp::Type::Foo". We also recommend considering L<MooseX::Types>.
=head2 Do not coerce Moose built-ins directly
=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>.
+covered in L<Moose::Manual::Types>.
=head2 Define all your types in one module
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
-
-Copyright 2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
=cut
projects / gitmo/Moose.git / blobdiff