X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FBestPractices.pod;h=f0edc9b0d40ad27db38288f84e285ead7cf88f75;hb=d5f016af3d56eec870efee8858352a4014879be2;hp=0e794094c95415d47306860b210dcc5a350aadb3;hpb=8a68781da0a1c7b8b019ff5347283dc38aea43b4;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Manual/BestPractices.pod b/lib/Moose/Manual/BestPractices.pod
index 0e79409..f0edc9b 100644
--- a/lib/Moose/Manual/BestPractices.pod
+++ b/lib/Moose/Manual/BestPractices.pod
@@ -13,34 +13,34 @@ and using them consistently makes everyone's life easier.
 Of course, as with any list of "best practices", these are really just
 opinions. Feel free to ignore us.
 
-=head2 C<no Moose> and immutabilize
+=head2 C<namespace::autoclean> and immutabilize
 
-We recommend that you end your Moose class definitions by removing the
-Moose sugar and making your class immutable.
+We recommend that you remove the Moose sugar and end your Moose class 
+definitions by making your class immutable.
 
   package Person;
 
   use Moose;
+  use namespace::autoclean;
 
   # extends, roles, attributes, etc.
 
   # methods
 
-  no Moose;
-
   __PACKAGE__->meta->make_immutable;
 
   1;
 
-The C<no Moose> bit simply good code hygiene, as it removes all the
-Moose keywords that are no longer needed once your class has been
-built.  C<make_immutable> relinquishes your right to make further
-changes to your class, and allows Moose to speed up a lot of things,
-most notably object construction.
+The C<use namespace::autoclean> bit is simply good code hygiene, as it removes
+imported symbols from  you class's namespace at the end of your package's
+compile cycle, including Moose keywords.  Once the class has been
+built, these keywords are not needed needed. The C<make_immutable>
+call allows Moose to speed up a lot of things, most notably object
+construction. The trade-off is that you can no longer change the class
+definition.
 
-A more generic way to unimport not only L<Moose>'s exports but also those from
-type libraries and other modules is L<namespace::clean> and
-L<namespace::autoclean>.
+C<no Moose;> may be used to unimport only Moose's imported symbols.
+L<namespace::clean> provides finer-grained control than L<namespace::autoclean>. 
 
 =head2 Never override C<new>
 
@@ -91,7 +91,7 @@ Also, keep your builder methods private.
 
 Lazy is good, and often solves initialization ordering problems. It's
 also good for deferring work that may never have to be done. If you're
-going to be lazy, use I<lazy_build> to save yourself some typing and
+going to be lazy, use C<lazy_build> to save yourself some typing and
 standardize names.
 
 =head2 Consider keeping clearers and predicates private
@@ -117,9 +117,9 @@ In order to declare such attributes, provide a private C<writer>
 parameter:
 
     has pizza => (
-        isa    => "Pizza",
-        is     => "ro",
-        writer => "_pizza",
+        is     => 'ro',
+        isa    => 'Pizza',
+        writer => '_pizza',
     );
 
 =head2 Think twice before changing an attribute's type in a subclass
@@ -132,13 +132,12 @@ of object in the parent class.
 
 Don't know what we're talking about? That's fine.
 
-=head2 Use L<MooseX::AttributeHelpers> instead of C<auto_deref>
+=head2 Use L<Moose::Meta::Attribute::Native> traits instead of C<auto_deref>
 
 The C<auto_deref> feature is a bit troublesome. Directly exposing a
 complex attribute is ugly. Instead, consider using
-L<MooseX::AttributeHelpers> to define an API that exposes those pieces
-of functionality that need exposing. Then you can expose just the
-functionality that you want.
+L<Moose::Meta::Attribute::Native> traits to define an API that exposes only
+necessary pieces of functionality.
 
 =head2 Always call C<inner> in the most specific subclass