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