953047297a6f10c0d2e9c8b3d733e7ab18a59ea0
[gitmo/Moose.git] / lib / Moose / Cookbook / Style.pod
1 =pod
2
3 =head1 NAME
4
5 Moose::Cookbook::Style - The latest in trendy Moose cuisine
6
7 =for authors
8
9 Please annotate all bad examples with comments so that they won't be copied by accodent
10
11 =cut
12
13 =head1 Benefits of Good Style
14
15 Good Moose style, as defined by this document, helps ensure your code has the
16 following desirable properties:
17
18 =over 4
19
20 =item Play well with others
21
22 Your code will be more reusable and easier to extend.
23
24 =item Ease maintenance
25
26 The code will be easier to understand because it follows an accepted set of
27 conventions and idioms.
28
29 This will help others maintaining your code, and also help you to get support
30 on IRC for instance.
31
32 =item Help Moose generate better code
33
34 By using the most appropriate features, the generated code will be safer and
35 more efficient.
36
37 =item Benefit from meta programming
38
39 Code that operates on the metaclass will benefit from clean meta definitions.
40
41 If you are manually converting argument types with C<around 'new'> there is no
42 meta data explaining your intention. If on the other hand you use coercions,
43 there is introspectable meta data that makes this clear.
44
45 This means that e.g. MooseX extensions that work by introspecting your class
46 will be able to do the right thing more often, because they don't need to
47 guess.
48
49 =back
50
51 =head1 Don't change C<new>
52
53 It is generally considered bad style to override L<Moose::Object/new> for a
54 number of reasons.
55
56 The first reason is consistency. Subclasses of your class and code
57 instantiating your class would be simpler if your constructor works closer to
58 the default.
59
60 The second reason is performance. By calling C<make_immutable> on your metaclass:
61
62     __PACKAGE__->meta->make_immutable;
63
64 And opting out of any class definition changes from that point on, you allow
65 Moose to create more efficient versions of certain generic methods. Moose will
66 generate a tight, optimal C<new> for you, based on the minimal set of features
67 you use.
68
69 Moose provides many features that allow you to do common object construction
70 tasks at the right level of abstraction.
71
72 When attributes have the ability to provide the necessary functionality, use
73 that. If that isn't sufficient, L<Moose::Object> has numerous features you can
74 use at construction time.
75
76 =head2 Use C<BUILD> instead of custom initialization or overriding C<new>
77
78 Instead of changing C<new>, do initialization in C<BUILD>.
79
80 The construction parameters are passed in, so you don't need to replicate
81 C<BUILDARGS>, and since C<BUILD> is called for each superclass that defines it,
82 you will never forget to invoke your initializers if you extend them.
83
84 =head2 Use C<default>, C<builder> or C<lazy_build>
85
86 To initialize attributes there is a plethora of methods preferable to assigning
87 the value at initialization time.
88
89 If you want to translate parameter data, use coercions.
90
91 If you want to ensure a parameter can't be overridden by the constructor, set
92 the C<init_arg> to C<undef> instead of overwriting it in C<BUILD>.
93
94 =head2 Use C<BUILDARGS> to alter C<@_> processing
95
96 If you need to change the way L<@_> is processed, use C<BUILDARGS>, instead of
97 wrapping C<new>. This ensures the behavior is subclassible, it keeps this logic
98 independent of the other aspects of construction, and can be made efficient
99 using C<make_immutable>.
100
101 =head1 Don't pollute the global type registry
102
103 =head2 Use fully qualified type names for your own data
104
105 L<MooseX::Types> provides a convenient method to do this.
106
107 If you define
108
109     # Bad style:
110
111     subtype Person => (
112         as 'Object',
113         where { $_->can("name") },
114     );
115
116 Then the global name C<Person> is registered, and this could conflict with
117 other bad usage of the sort.
118
119 Instead, prefix type name with your project namespace, or class name:   
120
121     subtype 'My::Foo::Person' => (
122         as 'Object',
123         where { $_->can("name") },
124     );
125
126 Or with L<MooseX::Types>:
127
128     use MooseX::Types::Moose qw(Object);
129
130     use MooseX::Types (
131         -declare => [qw(Person)],
132     );
133     
134     subtype Person() => ( # note parenthesis, "Person" is a function, not a string
135         as Object, # MooseX::Types::Moose exported it
136         where { $_->can("name") },
137     );
138
139 =head3 Coerce in a subtype
140
141 Likewise use fully qualified subtypes of other types for defining coercions, so
142 that they won't affect unrelated code, causing action at a distance.
143
144 This is important because the type registry is global, kind of like the symbol
145 table.
146
147 This means that code like:
148
149     # Bad style:
150
151     coerce ArrayRef => (
152         from Str => via { [ split /,/ ] },
153     );
154
155 Will add a coercion to B<all> attributes like:
156
157     has foo => (
158         isa => "ArrayRef",
159         coerce => 1,
160     );
161
162 in a specific way.
163
164 =head1 Clean up your package
165
166 Use C<namespace::clean> or C<no Moose> to remove the sugar exports.
167
168 This will make sure the sugar isn't accidentally called as methods on your objects.
169
170 For instance:
171
172     $obj->can("has");
173
174 will return true, even though C<has> is not a method.
175
176 =head1 Accept no substitutes
177
178 By substitutes I mean hacks instead of "proper" solutions.
179
180 When you have a tricky requirement, refrain from abusing Moose or MooseX:: or
181 whatever it is you are using.
182
183 Instead, drop by IRC and discuss it. Most of the time a crazy idea can either
184 be simplified, or it will spawn a clean, reliable feature to whatever package
185 you are using.
186
187 This will improve your code and also share the benefit with others.
188
189 =head1 AUTHOR
190
191 Yuval (nothingmuch) Kogman
192
193 =head1 COPYRIGHT AND LICENSE
194
195 Copyright 2006-2008 by Infinity Interactive, Inc.
196
197 L<http://www.iinteractive.com>
198
199 This library is free software; you can redistribute it and/or modify
200 it under the same terms as Perl itself.
201
202 =cut