uc/lc consistency, typo and style fixes for Moose::Manual documents

[gitmo/Moose.git] / lib / Moose / Manual / BestPractices.pod

=pod

=head1 NAME

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

=head1 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.

=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.

  package Person;

  use Moose;

  # extends, roles, attributes, etc.

  # methods

  no Moose;

  __PACKAGE__->meta->make_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.

=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
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
I<non-hashref> single argument.

=head2 Don't use the C<initializer> feature

Don't know what we're talking about? That's fine.

=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.

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

Also, keep your builder methods private.

=head2 Use C<lazy_build>

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 I<lazy_build> to save yourself some typing and
standardize names.

=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
by default.

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

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 I<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.

=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>

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.

=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.

=head2 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

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

=head1 AUTHOR

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