lib/Moose/Manual/BestPractices.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::BestPractices - Get the most out of Moose
   6
   7 =head1 RECOMMENDATIONS
   8
   9 Moose has a lot of features, and there's definitely more than one way
  10 to do it. However, we think that picking a subset of these features
  11 and using them consistently makes everyone's life easier.
  12
  13 Of course, as with any list of "best practices", these are really just
  14 opinions. Feel free to ignore us.
  15
  16 =head2 C<namespace::autoclean> and immutabilize
  17
  18 We recommend that you remove the Moose sugar and end your Moose class
  19 definitions by making your class immutable.
  20
  21   package Person;
  22
  23   use Moose;
  24   use namespace::autoclean;
  25
  26   # extends, roles, attributes, etc.
  27
  28   # methods
  29
  30   __PACKAGE__->meta->make_immutable;
  31
  32   1;
  33
  34 The C<use namespace::autoclean> bit is simply good code hygiene, as it removes
  35 imported symbols from  you class's namespace at the end of your package's
  36 compile cycle, including Moose keywords.  Once the class has been
  37 built, these keywords are not needed.
  38
  39 The C<make_immutable> call allows Moose to speed up a lot of things, most
  40 notably object construction. The trade-off is that you can no longer change
  41 the class definition.
  42
  43 =head2 Never override C<new>
  44
  45 Overriding C<new> is a very bad practice. Instead, you should use a
  46 C<BUILD> or C<BUILDARGS> methods to do the same thing. When you
  47 override C<new>, Moose can no longer inline a constructor when your
  48 class is immutabilized.
  49
  50 There are two good reasons to override C<new>. One, you are writing a
  51 MooseX extension that provides its own L<Moose::Object> subclass
  52 I<and> a subclass of L<Moose::Meta::Method::Constructor> to inline the
  53 constructor. Two, you are subclassing a non-Moose parent.
  54
  55 If you know how to do that, you know when to ignore this best practice
  56 ;)
  57
  58 =head2 Always call the original/parent C<BUILDARGS>
  59
  60 If you C<override> the C<BUILDARGS> method in your class, make sure to play
  61 nice and call C<super()> to handle cases you're not checking for explicitly.
  62
  63 The default C<BUILDARGS> method in L<Moose::Object> handles both a
  64 list and hashref of named parameters correctly, and also checks for a
  65 I<non-hashref> single argument.
  66
  67 =head2 Provide defaults whenever possible, otherwise use C<required>
  68
  69 When your class provides defaults, this makes constructing new objects
  70 simpler. If you cannot provide a default, consider making the
  71 attribute C<required>.
  72
  73 If you don't do either, an attribute can simply be left unset,
  74 increasing the complexity of your object, because it has more possible
  75 states that you or the user of your class must account for.
  76
  77 =head2 Use C<builder> instead of C<default> most of the time
  78
  79 Builders can be inherited, they have explicit names, and they're just
  80 plain cleaner.
  81
  82 However, I<do> use a default when the default is a non-reference,
  83 I<or> when the default is simply an empty reference of some sort.
  84
  85 Also, keep your builder methods private.
  86
  87 =head2 Be C<lazy>
  88
  89 Lazy is good, and often solves initialization ordering problems. It's also
  90 good for deferring work that may never have to be done. Make your attributes
  91 C<lazy> unless they're C<required> or have trivial defaults.
  92
  93 =head2 Consider keeping clearers and predicates private
  94
  95 Does everyone I<really> need to be able to clear an attribute?
  96 Probably not. Don't expose this functionality outside your class
  97 by default.
  98
  99 Predicates are less problematic, but there's no reason to make your
 100 public API bigger than it has to be.
 101
 102 =head2 Default to read-only, and consider keeping writers private
 103
 104 Making attributes mutable just means more complexity to account for in
 105 your program. The alternative to mutable state is to encourage users
 106 of your class to simply make new objects as needed.
 107
 108 If you I<must> make an attribute read-write, consider making the
 109 writer a separate private method. Narrower APIs are easy to maintain,
 110 and mutable state is trouble.
 111
 112 In order to declare such attributes, provide a private C<writer>
 113 parameter:
 114
 115     has pizza => (
 116         is     => 'ro',
 117         isa    => 'Pizza',
 118         writer => '_pizza',
 119     );
 120
 121 =head2 Think twice before changing an attribute's type in a subclass
 122
 123 Down this path lies great confusion. If the attribute is an object
 124 itself, at least make sure that it has the same interface as the type
 125 of object in the parent class.
 126
 127 =head2 Don't use the C<initializer> feature
 128
 129 Don't know what we're talking about? That's fine.
 130
 131 =head2 Use L<Moose::Meta::Attribute::Native> traits instead of C<auto_deref>
 132
 133 The C<auto_deref> feature is a bit troublesome. Directly exposing a complex
 134 attribute is ugly. Instead, consider using L<Moose::Meta::Attribute::Native>
 135 traits to define an API that only exposes the necessary pieces of
 136 functionality.
 137
 138 =head2 Always call C<inner> in the most specific subclass
 139
 140 When using C<augment> and C<inner>, we recommend that you call
 141 C<inner> in the most specific subclass of your hierarchy. This makes
 142 it possible to subclass further and extend the hierarchy without
 143 changing the parents.
 144
 145 =head2 Namespace your types
 146
 147 Use some sort of namespacing convention for type names. We recommend something
 148 like "MyApp::Type::Foo". We also recommend considering L<MooseX::Types>.
 149
 150 =head2 Do not coerce Moose built-ins directly
 151
 152 If you define a coercion for a Moose built-in like C<ArrayRef>, this
 153 will affect every application in the Perl interpreter that uses this
 154 type.
 155
 156     # very naughty!
 157     coerce 'ArrayRef'
 158         => from Str
 159         => via { [ split /,/ ] };
 160
 161 Instead, create a subtype and coerce that:
 162
 163     subtype 'My::ArrayRef' => as 'ArrayRef';
 164
 165     coerce 'My::ArrayRef'
 166         => from 'Str'
 167         => via { [ split /,/ ] };
 168
 169 =head2 Do not coerce class names directly
 170
 171 Just as with Moose built-in types, a class type is global for the
 172 entire interpreter. If you add a coercion for that class name, it can
 173 have magical side effects elsewhere:
 174
 175     # also very naughty!
 176     coerce 'HTTP::Headers'
 177         => from 'HashRef'
 178         => via { HTTP::Headers->new( %{$_} ) };
 179
 180 Instead, we can create an "empty" subtype for the coercion:
 181
 182     subtype 'My::HTTP::Headers' => as class_type('HTTP::Headers');
 183
 184     coerce 'My::HTTP::Headers'
 185         => from 'HashRef'
 186         => via { HTTP::Headers->new( %{$_} ) };
 187
 188 =head2 Use coercion instead of unions
 189
 190 Consider using a type coercion instead of a type union. This was
 191 covered in L<Moose::Manual::Types>.
 192
 193 =head2 Define all your types in one module
 194
 195 Define all your types and coercions in one module. This was also
 196 covered in L<Moose::Manual::Types>.
 197
 198 =head1 BENEFITS OF BEST PRACTICES
 199
 200 Following these practices has a number of benefits.
 201
 202 It helps ensure that your code will play nice with others, making it
 203 more reusable and easier to extend.
 204
 205 Following an accepted set of idioms will make maintenance easier,
 206 especially when someone else has to maintain your code. It will also
 207 make it easier to get support from other Moose users, since your code
 208 will be easier to digest quickly.
 209
 210 Some of these practices are designed to help Moose do the right thing,
 211 especially when it comes to immutabilization. This means your code
 212 will be faster when immutabilized.
 213
 214 Many of these practices also help get the most out of meta
 215 programming. If you used an overridden C<new> to do type coercion by
 216 hand, rather than defining a real coercion, there is no introspectable
 217 metadata. This sort of thing is particularly problematic for MooseX
 218 extensions which rely on introspection to do the right thing.
 219
 220 =head1 AUTHOR
 221
 222 Yuval (nothingmuch) Kogman
 223
 224 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 225
 226 =head1 COPYRIGHT AND LICENSE
 227
 228 Copyright 2009-2010 by Infinity Interactive, Inc.
 229
 230 L<http://www.iinteractive.com>
 231
 232 This library is free software; you can redistribute it and/or modify
 233 it under the same terms as Perl itself.
 234
 235 =cut