Use required_method objects, not names, in ToRole

[gitmo/Moose.git] / lib / Moose / Manual / BestPractices.pod

diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod
index 691f7d0..30c5673 100644 (file)
--- a/lib/Moose/Manual/BestPractices.pod
+++ b/lib/Moose/Manual/BestPractices.pod
@@ -134,8 +134,11 @@ changing the parents.
 =head2 Namespace your types
 
 Use some sort of namespacing convention for type names. We recommend
-something like "MyApp.Type.Foo". I<Never> use "::" as the namespace
-separator, since that overlaps with actual class names.
+something like "MyApp::Type::Foo".
+
+If you're intending to package your types up for re-use using
+L<MooseX::Types> later, avoid using characters that are invalid in
+perl identifiers such as a space or period.
 
 =head2 Do not coerce Moose built-ins directly
 
@@ -146,15 +149,15 @@ type.
     # very naughty!
     coerce 'ArrayRef'
         => from Str
-            => via { [ split /,/ ] };
+        => via { [ split /,/ ] };
 
 Instead, create a subtype and coerce that:
 
-    subtype 'My.ArrayRef' => as 'ArrayRef';
+    subtype 'My::ArrayRef' => as 'ArrayRef';
 
-    coerce 'My.ArrayRef'
+    coerce 'My::ArrayRef'
         => from 'Str'
-            => via { [ split /,/ ] };
+        => via { [ split /,/ ] };
 
 =head2 Do not coerce class names directly
 
@@ -165,15 +168,15 @@ have magical side effects elsewhere:
     # also very naughty!
     coerce 'HTTP::Headers'
         => from 'HashRef'
-            => via { HTTP::Headers->new( %{$_} ) };
+        => via { HTTP::Headers->new( %{$_} ) };
 
 Instead, we can create an "empty" subtype for the coercion:
 
-    subtype 'My.HTTP::Headers' => as class_type('HTTP::Headers');
+    subtype 'My::HTTP::Headers' => as class_type('HTTP::Headers');
 
-    coerce 'My.HTTP::Headers'
+    coerce 'My::HTTP::Headers'
         => from 'HashRef'
-            => via { HTTP::Headers->new( %{$_} ) };
+        => via { HTTP::Headers->new( %{$_} ) };
 
 =head2 Use coercion instead of unions
 
@@ -204,7 +207,7 @@ will be faster when immutabilized.
 Many of these practices also help get the most out of meta
 programming. If you used an overridden C<new> to do type coercion by
 hand, rather than defining a real coercion, there is no introspectable
-metadata. This sort of thing is particularly problematic MooseX
+metadata. This sort of thing is particularly problematic for MooseX
 extensions which rely on introspection to do the right thing.
 
 =head1 AUTHOR