switch to :: for types in BestPractices, note the perl identifier requirement for...

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

diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod
index 0c74d75..c73f4d3 100644 (file)
--- a/lib/Moose/Manual/BestPractices.pod
+++ b/lib/Moose/Manual/BestPractices.pod
@@ -42,10 +42,10 @@ C<BUILD> or C<BUILDARGS> methods to do the same thing. When you
 override C<new>, Moose can no longer inline a constructor when your
 class is immutabilized.
 
-The only reason to override C<new> is if you are writing a MooseX
-extension that provides its own L<Moose::Object> subclass I<and> a
-subclass of L<Moose::Meta::Method::Constructor> to inline the
-constructor.
+There are two good reasons to override C<new>. One, you are writing a
+MooseX extension that provides its own L<Moose::Object> subclass
+I<and> a subclass of L<Moose::Meta::Method::Constructor> to inline the
+constructor. Two, you are subclassing a non-Moose parent.
 
 If you know how to do that, you know when to ignore this best practice
 ;)
@@ -134,8 +134,9 @@ 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 MooseX::Types later, avoid using
+characters that are invalid in perl identifiers such as ' ' and '.'.
 
 =head2 Do not coerce Moose built-ins directly