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, and making classes
  36 immutable speeds up a lot of things, most notably object construction.
  37
  38 =head2 Always call C<SUPER::BUILDARGS>
  39
  40 If you override the C<BUILDARGS> method in your class, make sure to
  41 play nice and call C<SUPER::BUILDARGS> to handle cases you're not
  42 checking for explicitly.
  43
  44 The default C<BUILDARGS> method in L<Moose::Object> handles both a
  45 list and hashref of named parameters correctly, and also checks for a
  46 I<non-hashref> single argument.
  47
  48 =head2 Don't use the C<initializer> feature
  49
  50 Don't know what we're talking about? That's fine.
  51
  52 =head2 Use C<builder> instead of C<default> most of the time
  53
  54 Builders can be inherited, they have explicit names, and they're just
  55 plain cleaner.
  56
  57 However, I<do> use a default when the default is a non-reference,
  58 I<or> when the default is simply an empty reference of some sort.
  59
  60 Also, keep your builder methods private.
  61
  62 =head2 Use C<lazy_build>
  63
  64 Lazy is good, and often solves initialization ordering problems. It's
  65 also good for deferring work that may never have to be done. If you're
  66 going to be lazy, use I<lazy_build> to save yourself some typing and
  67 standardize names.
  68
  69 =head2 Consider keeping clearers and predicates private
  70
  71 Does everyone I<really> need to be able to clear an attribute?
  72 Probably not. Don't expose this functionality outside your class
  73 by default.
  74
  75 Predicates are less problematic, but there's no reason to make your
  76 public API bigger than it has to be.
  77
  78 =head2 Default to read-only, and consider keeping writers private
  79
  80 Making attributes mutable just means more complexity to account for in
  81 your program. The alternative to mutable state is to encourage users
  82 of your class to simply make new objects as needed.
  83
  84 If you I<must> make an attribute read-write, consider making the
  85 writer a separate private method. Narrower APIs are easy to maintain,
  86 and mutable state is trouble.
  87
  88 =head2 Think twice before changing an attribute's type in a subclass
  89
  90 Down this path lies great confusion. If the attribute is an object
  91 itself, at least make sure that it has the same interface as the type
  92 of object in the parent class.
  93
  94 =head2 Use L<MooseX::AttributeHelpers> instead of C<auto_deref>
  95
  96 The C<auto_deref> feature is a bit troublesome. Directly exposing a
  97 complex attribute is ugly. Instead, consider using
  98 L<MooseX::AttributeHelpers> to define an API that exposes those pieces
  99 of functionality that need exposing. Then you can expose just the
 100 functionality that you want.
 101
 102 =head2 Always call C<inner> in the most specific subclass
 103
 104 When using C<augment> and C<inner>, we recommend that you call
 105 C<inner> in the most specific subclass of your hierarchy. This makes
 106 it possible to subclass further and extend the hierarchy without
 107 changing the parents.
 108
 109 =head2 Namespace your types
 110
 111 Use some sort of namespacing convention for type names. We recommend
 112 something like "MyApp.Type.Foo". I<Never> use "::" as the namespace
 113 separator, since that overlaps with actual class names.
 114
 115 =head2 Coercion instead of unions
 116
 117 Consider using a type coercion instead of a type union. This was
 118 covered at length in L<Moose::Manual::Types>.
 119
 120 =head2 Define all your types in one module
 121
 122 Define all your types and coercions in one module. This was also
 123 covered in L<Moose::Manual::Types>.
 124
 125 =head1 AUTHOR
 126
 127 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 128
 129 =head1 COPYRIGHT AND LICENSE
 130
 131 Copyright 2009 by Infinity Interactive, Inc.
 132
 133 L<http://www.iinteractive.com>
 134
 135 This library is free software; you can redistribute it and/or modify
 136 it under the same terms as Perl itself.
 137
 138 =cut