lib/Moose/Manual/BestPractices.pod

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