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