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