1Moose::Manual::BestPracUtsiecresC(o3n)tributed Perl DocuMmoeonstea:t:iMoannual::BestPractices(3)
2
6 Moose::Manual::BestPractices - Get the most out of Moose
7
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 and
11 using them consistently makes everyone's life easier.
12 Of course, as with any list of "best practices", these are really just
14 opinions. Feel free to ignore us.
15 "namespace::autoclean" and immutabilize
17 We recommend that you remove the Moose sugar and end your Moose class
18 definitions by making your class immutable.
19 package Person;
21 use Moose;
23 use namespace::autoclean;
24 # extends, roles, attributes, etc.
26 # methods
28 __PACKAGE__->meta->make_immutable;
30 1;
32 The "use namespace::autoclean" bit is simply good code hygiene, as it
34 removes imported symbols from you class's namespace at the end of your
35 package's compile cycle, including Moose keywords. Once the class has
36 been built, these keywords are not needed. The "make_immutable" call
37 allows Moose to speed up a lot of things, most notably object
38 construction. The trade-off is that you can no longer change the class
39 definition.
40 You can also write "no Moose" to unimport only Moose's imported
42 symbols. The namespace::clean module is another alternative, providing
43 finer-grained control than namespace::autoclean.
44 Never override "new"
46 Overriding "new" is a very bad practice. Instead, you should use a
47 "BUILD" or "BUILDARGS" methods to do the same thing. When you override
48 "new", Moose can no longer inline a constructor when your class is
49 immutabilized.
50 There are two good reasons to override "new". One, you are writing a
52 MooseX extension that provides its own Moose::Object subclass and a
53 subclass of Moose::Meta::Method::Constructor to inline the constructor.
54 Two, you are subclassing a non-Moose parent.
55 If you know how to do that, you know when to ignore this best practice
57 ;)
58 Always call "SUPER::BUILDARGS"
60 If you override the "BUILDARGS" method in your class, make sure to play
61 nice and call "SUPER::BUILDARGS" to handle cases you're not checking
62 for explicitly.
63 The default "BUILDARGS" method in Moose::Object handles both a list and
65 hashref of named parameters correctly, and also checks for a non-
66 hashref single argument.
67 Provide defaults whenever possible, otherwise use "required"
69 When your class provides defaults, this makes constructing new objects
70 simpler. If you cannot provide a default, consider making the attribute
71 "required".
72 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 Use "builder" instead of "default" most of the time
78 Builders can be inherited, they have explicit names, and they're just
79 plain cleaner.
80 However, do use a default when the default is a non-reference, or when
82 the default is simply an empty reference of some sort.
83 Also, keep your builder methods private.
85 Use "lazy_build"
87 Lazy is good, and often solves initialization ordering problems. It's
88 also good for deferring work that may never have to be done. If you're
89 going to be lazy, use "lazy_build" to save yourself some typing and
90 standardize names.
91 Consider keeping clearers and predicates private
93 Does everyone really need to be able to clear an attribute? Probably
94 not. Don't expose this functionality outside your class by default.
95 Predicates are less problematic, but there's no reason to make your
97 public API bigger than it has to be.
98 Default to read-only, and consider keeping writers private
100 Making attributes mutable just means more complexity to account for in
101 your program. The alternative to mutable state is to encourage users of
102 your class to simply make new objects as needed.
103 If you must make an attribute read-write, consider making the writer a
105 separate private method. Narrower APIs are easy to maintain, and
106 mutable state is trouble.
107 In order to declare such attributes, provide a private "writer"
109 parameter:
110 has pizza => (
112 is => 'ro',
113 isa => 'Pizza',
114 writer => '_pizza',
115 );
116 Think twice before changing an attribute's type in a subclass
118 Down this path lies great confusion. If the attribute is an object
119 itself, at least make sure that it has the same interface as the type
120 of object in the parent class.
121 Don't use the "initializer" feature
123 Don't know what we're talking about? That's fine.
124 Use Moose::Meta::Attribute::Native traits instead of "auto_deref"
126 The "auto_deref" feature is a bit troublesome. Directly exposing a
127 complex attribute is ugly. Instead, consider using
128 Moose::Meta::Attribute::Native traits to define an API that exposes
129 only necessary pieces of functionality.
130 Always call "inner" in the most specific subclass
132 When using "augment" and "inner", we recommend that you call "inner" in
133 the most specific subclass of your hierarchy. This makes it possible to
134 subclass further and extend the hierarchy without changing the parents.
135 Namespace your types
137 Use some sort of namespacing convention for type names. We recommend
138 something like "MyApp::Type::Foo".
139 If you're intending to package your types up for re-use using
141 MooseX::Types later, avoid using characters that are invalid in perl
142 identifiers such as a space or period.
143 Do not coerce Moose built-ins directly
145 If you define a coercion for a Moose built-in like "ArrayRef", this
146 will affect every application in the Perl interpreter that uses this
147 type.
148 # very naughty!
150 coerce 'ArrayRef'
151 => from Str
152 => via { [ split /,/ ] };
153 Instead, create a subtype and coerce that:
155 subtype 'My::ArrayRef' => as 'ArrayRef';
157 coerce 'My::ArrayRef'
159 => from 'Str'
160 => via { [ split /,/ ] };
161 Do not coerce class names directly
163 Just as with Moose built-in types, a class type is global for the
164 entire interpreter. If you add a coercion for that class name, it can
165 have magical side effects elsewhere:
166 # also very naughty!
168 coerce 'HTTP::Headers'
169 => from 'HashRef'
170 => via { HTTP::Headers->new( %{$_} ) };
171 Instead, we can create an "empty" subtype for the coercion:
173 subtype 'My::HTTP::Headers' => as class_type('HTTP::Headers');
175 coerce 'My::HTTP::Headers'
177 => from 'HashRef'
178 => via { HTTP::Headers->new( %{$_} ) };
179 Use coercion instead of unions
181 Consider using a type coercion instead of a type union. This was
182 covered at length in Moose::Manual::Types.
183 Define all your types in one module
185 Define all your types and coercions in one module. This was also
186 covered in Moose::Manual::Types.
187
189 Following these practices has a number of benefits.
190 It helps ensure that your code will play nice with others, making it
192 more reusable and easier to extend.
193 Following an accepted set of idioms will make maintenance easier,
195 especially when someone else has to maintain your code. It will also
196 make it easier to get support from other Moose users, since your code
197 will be easier to digest quickly.
198 Some of these practices are designed to help Moose do the right thing,
200 especially when it comes to immutabilization. This means your code will
201 be faster when immutabilized.
202 Many of these practices also help get the most out of meta programming.
204 If you used an overridden "new" to do type coercion by hand, rather
205 than defining a real coercion, there is no introspectable metadata.
206 This sort of thing is particularly problematic for MooseX extensions
207 which rely on introspection to do the right thing.
208
210 Yuval (nothingmuch) Kogman
211 Dave Rolsky <autarch@urth.org>
213
215 Copyright 2009 by Infinity Interactive, Inc.
216 <http://www.iinteractive.com>
218 This library is free software; you can redistribute it and/or modify it
220 under the same terms as Perl itself.
221perl v5.12.2 2010-08-21 Moose::Manual::BestPractices(3)