From: Dave Rolsky Date: Wed, 11 Feb 2009 19:19:54 +0000 (+0000) Subject: Merged the content from Moose::Cookbook::Style into X-Git-Tag: 0.69~23 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1ad2aa8ed94a903175c59a26a6981877b7fd817c;p=gitmo%2FMoose.git Merged the content from Moose::Cookbook::Style into Moose::Manual::BestPractices, and made the former a pointer to the latter. --- diff --git a/lib/Moose/Cookbook/Style.pod b/lib/Moose/Cookbook/Style.pod index 1e5059b..35429ed 100644 --- a/lib/Moose/Cookbook/Style.pod +++ b/lib/Moose/Cookbook/Style.pod @@ -2,208 +2,12 @@ =head1 NAME -Moose::Cookbook::Style - The latest in trendy Moose cuisine +Moose::Cookbook::Style - Expanded into Moose::Manual::BestPractices, so go read that -=for authors +=head1 DESCRIPTION -Please annotate all bad examples with comments so that they won't be copied by -accident - -=cut - -=head1 Benefits of Good Style - -Good Moose style, as defined by this document, helps ensure your code has the -following desirable properties: - -=over 4 - -=item Play well with others - -Your code will be more reusable and easier to extend. - -=item Ease maintenance - -The code will be easier to understand because it follows an accepted set of -conventions and idioms. - -This will help others maintaining your code, and also help you to get support -on IRC for instance. - -=item Help Moose generate better code - -By using the most appropriate features, the generated code will be safer and -more efficient. - -=item Benefit from meta programming - -Code that operates on the metaclass will benefit from clean meta definitions. - -If you are manually converting argument types with C there is no -meta data explaining your intention. If on the other hand you use coercions, -there is introspectable meta data that makes this clear. - -This means that e.g. MooseX extensions that work by introspecting your class -will be able to do the right thing more often, because they don't need to -guess. - -=back - -=head1 Don't change C - -It is generally considered bad style to override L for a -number of reasons. - -The first reason is consistency. Subclasses of your class and code -instantiating your class would be simpler if your constructor works closer to -the default. - -The second reason is performance. By calling C on your metaclass: - - __PACKAGE__->meta->make_immutable; - -And opting out of any class definition changes from that point on, you allow -Moose to create more efficient versions of certain generic methods. Moose will -generate a tight, optimal C for you, based on the minimal set of features -you use. - -Moose provides many features that allow you to do common object construction -tasks at the right level of abstraction. - -When attributes have the ability to provide the necessary functionality, use -that. If that isn't sufficient, L has numerous features you can -use at construction time. - -=head2 Use C instead of custom initialization or overriding C - -Instead of changing C, do initialization in C. - -The construction parameters are passed in, so you don't need to replicate -C, and since C is called for each superclass that defines it, -you will never forget to invoke your initializers if you extend them. - -=head2 Use C, C or C - -To initialize attributes there is a plethora of methods preferable to assigning -the value at initialization time. - -If you want to translate parameter data, use coercions. - -If you want to ensure a parameter can't be overridden by the constructor, set -the C to C instead of overwriting it in C. - -=head2 Use C to alter C<@_> processing - -If you need to change the way C<@_> is processed, for example for -C<< Class->new( $single_param ) >>, use C instead of wrapping -C. This ensures the behavior is subclassable, it keeps this logic -independent of the other aspects of construction, and can be made efficient -using C. - -=head1 Don't pollute the global type registry - -=head2 Use fully qualified type names for your own data - -L provides a convenient method to do this. - -If you define - - # Bad style: - - subtype Person => ( - as 'Object', - where { $_->can("name") }, - ); - -Then the global name C is registered, and this could conflict with -other bad usage of the sort. - -Instead, prefix type name with your project namespace, or class name: - - subtype 'My::Foo::Person' => ( - as 'Object', - where { $_->can("name") }, - ); - -Or with L: - - use MooseX::Types::Moose qw(Object); - - use MooseX::Types ( - -declare => [qw(Person)], - ); - - subtype Person() => ( # note parenthesis, "Person" is a function, not a string - as Object, # MooseX::Types::Moose exported it - where { $_->can("name") }, - ); - -=head3 Coerce in a subtype - -Likewise use fully qualified subtypes of other types for defining coercions, so -that they won't affect unrelated code, causing action at a distance. - -This is important because the type registry is global, kind of like the symbol -table. - -This means that code like: - - # Bad style: - - coerce ArrayRef => ( - from Str => via { [ split /,/ ] }, - ); - -Will add a coercion to B attributes like: - - has foo => ( - isa => "ArrayRef", - coerce => 1, - ); - -when the actual coercion applies only to your specific cases. - -=head1 Clean up your package - -Use C or C to remove the sugar exports. - -This will make sure the sugar isn't accidentally called as methods on your objects. - -For instance: - - $obj->can("has"); - -will return true, even though C is not a method. - -If you choose L, make sure to keep the C method if you -want to use it for introspection: - - use namespace::clean -except => "meta"; - -=head1 Accept no substitutes - -By substitutes I mean hacks instead of "proper" solutions. - -When you have a tricky requirement, refrain from abusing Moose or MooseX:: or -whatever it is you are using. - -Instead, drop by IRC and discuss it. Most of the time a crazy idea can either -be simplified, or it will spawn a clean, reliable feature to whatever package -you are using. - -This will improve your code and also share the benefit with others. - -=head1 AUTHOR - -Yuval (nothingmuch) Kogman - -=head1 COPYRIGHT AND LICENSE - -Copyright 2006-2009 by Infinity Interactive, Inc. - -L - -This library is free software; you can redistribute it and/or modify it under -the same terms as Perl itself. +The style cookbook has been replaced by +L. This POD document still exists for +the benefit of anyone out there who might've linked to it in the past. =cut diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod index cab1af9..157e499 100644 --- a/lib/Moose/Manual/BestPractices.pod +++ b/lib/Moose/Manual/BestPractices.pod @@ -35,6 +35,21 @@ Moose sugar and making your class immutable. The C bit is simply good code hygiene, and making classes immutable speeds up a lot of things, most notably object construction. +=head2 Never override C + +Overriding C is a very bad practice. Instead, you should use a +C or C methods to do the same thing. When you +override C, Moose can no longer inline a constructor when your +class is immutablized. + +The only reason to override C is if you are writing a MooseX +extension that provides its own L subclass I a +subclass of L to inline the +constructor. + +If you know how to do that, you know when to ignore this best practice +;) + =head2 Always call C If you override the C method in your class, make sure to @@ -45,9 +60,15 @@ The default C method in L handles both a list and hashref of named parameters correctly, and also checks for a I single argument. -=head2 Don't use the C feature +=head2 Provide defaults whenever possible, otherwise use C -Don't know what we're talking about? That's fine. +When your class provides defaults, this makes constructing new objects +simpler. If you cannot provide a default, consider making the +attribute C. + +If you don't do either, an attribute can simply be left unset, +increasing the complexity of your object, because it has more possible +states that you or the user of your class must account for. =head2 Use C instead of C most of the time @@ -91,6 +112,10 @@ Down this path lies great confusion. If the attribute is an object itself, at least make sure that it has the same interface as the type of object in the parent class. +=head2 Don't use the C feature + +Don't know what we're talking about? That's fine. + =head2 Use L instead of C The C feature is a bit troublesome. Directly exposing a @@ -112,7 +137,45 @@ Use some sort of namespacing convention for type names. We recommend something like "MyApp.Type.Foo". I use "::" as the namespace separator, since that overlaps with actual class names. -=head2 Coercion instead of unions +=head2 Do not coerce Moose built-ins directly + +If you define a coercion for a Moose built-in like C, this +will affect every application in the Perl interpreter that uses this +type. + + # very naughty! + coerce 'ArrayRef' + => from Str + => via { [ split /,/ ] }; + +Instead, create a subtype and coerce that: + + subtype 'My.ArrayRef' => as 'ArrayRef'; + + coerce 'My.ArrayRef' + => from 'Str' + => via { [ split /,/ ] }; + +=head2 Do not coerce class names directly + +Just as with Moose built-in types, a class type is global for the +entire interpreter. If you add a coercion for that class name, it can +have magical side effects elsewhere: + + # also very naughty! + coerce 'HTTP::Headers' + => from 'HashRef' + => via { HTTP::Headers->new( %{$_} ) }; + +Instead, we can create an "empty" subtype for the coercion: + + subtype 'My.HTTP.Headers' => as class_type('HTTP::Headers'); + + coerce 'My.HTTP.Headers' + => from 'HashRef' + => via { HTTP::Headers->new( %{$_} ) }; + +=head2 Use coercion instead of unions Consider using a type coercion instead of a type union. This was covered at length in L. @@ -122,8 +185,32 @@ covered at length in L. Define all your types and coercions in one module. This was also covered in L. +=head1 BENEFITS OF BEST PRACTICES + +Following these practices has a number of benefits. + +It helps ensure that your code will play nice with others, making it +more reusable and easier to extend. + +Following an accepted set of idioms will make maintenance easier, +especially when someone else has to maintain your code. It will also +make it easier to get support from other Moose users, since your code +will be easier to digest quickly. + +Some of these practices are designed to help Moose do the right thing, +especially when it comes to immutabilization. This means your code +will be faster when immutabilized. + +Many of these practices also help get the most out of meta +programming. If you used an overridden C to do type coercion by +hand, rather than defining a real coercion, there is no introspectable +metadata. This sort of thing is particuarly problematic MooseX +extensions which rely on introspection to do the right thing. + =head1 AUTHOR +Yuval (nothingmuch) Kogman + Dave Rolsky Eautarch@urth.orgE =head1 COPYRIGHT AND LICENSE