-=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
Of course, as with any list of "best practices", these are really just
opinions. Feel free to ignore us.
-=head2 C<no Moose> and immutabilize
+=head2 C<namespace::autoclean> and immutabilize
-We recommend that you end your Moose class definitions by removing the
-Moose sugar and making your class immutable.
+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
- no Moose;
-
__PACKAGE__->meta->make_immutable;
1;
-The C<no Moose> bit is simply good code hygiene, as it removes all the
-Moose keywords from your class's namespace. 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 tradeoff is that you can no longer change the class
-definition.
+The C<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 C<no Moose> at the end
+of your package).
-A more generic way to unimport not only L<Moose>'s exports but also
-those from type libraries and other modules is to use
-L<namespace::clean> or 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
Don't know what we're talking about? That's fine.
-=head2 Use L<MooseX::AttributeHelpers> instead of C<auto_deref>
+=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<MooseX::AttributeHelpers> to define an API that exposes those pieces
-of functionality that need exposing. Then you can expose just the
-functionality that you want.
+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