Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Manual::BestPraUsereContributed Perl DocMoose::Manual::BestPractices(3)

NAME
       Moose::Manual::BestPractices - Get the most out of Moose

VERSION
       version 2.2005

RECOMMENDATIONS
       Moose has a lot of features, and	there's	definitely more	than one way
       to do it. However, we think that	picking	a subset of these features 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.

   "namespace::autoclean" and immutabilize
       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

	 __PACKAGE__->meta->make_immutable;

	 1;

       The "use	namespace::autoclean" bit is simply good code hygiene, as it
       removes imported	symbols	from your 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. (This	is preferred to
       placing "no Moose" at the end of	your package).

       The "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.

   Never override "new"
       Overriding "new"	is a very bad practice.	Instead, you should use	a
       "BUILD" or "BUILDARGS" methods to do the	same thing. When you override
       "new", Moose can	no longer inline a constructor when your class is
       immutabilized.

       There are two good reasons to override "new". One, you are writing a
       MooseX extension	that provides its own Moose::Object subclass and a
       subclass	of 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
       ;)

   Always call the original/parent "BUILDARGS"
       If you "override" the "BUILDARGS" method	in your	class, make sure to
       play nice and call "super()" to handle cases you're not checking	for
       explicitly.

       The default "BUILDARGS" method in Moose::Object handles both a list and
       hashref of named	parameters correctly, and also checks for a non-
       hashref single argument.

   Provide defaults whenever possible, otherwise use "required"
       When your class provides	defaults, this makes constructing new objects
       simpler.	If you cannot provide a	default, consider making the attribute
       "required".

       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.

   Use "builder" instead of "default" most of the time
       Builders	can be inherited, they have explicit names, and	they're	just
       plain cleaner.

       However,	do use a default when the default is a non-reference, or when
       the default is simply an	empty reference	of some	sort.

       Also, keep your builder methods private.

   Be "lazy"
       Lazy is good, and often solves initialization ordering problems.	It's
       also good for deferring work that may never have	to be done. Make your
       attributes "lazy" unless	they're	"required" or have trivial defaults.

   Consider keeping clearers and predicates private
       Does everyone really need to be able to clear an	attribute?  Probably
       not. Don't expose this functionality outside your class by default.

       Predicates are less problematic,	but there's no reason to make your
       public API bigger than it has to	be.

   Avoid "lazy_build"
       As described above, you rarely actually need a clearer or a predicate.
       "lazy_build" adds both to your public API, which	exposes	you to use
       cases that you must now test for. It's much better to avoid adding them
       until you really	need them - use	explicit "lazy"	and "builder" options
       instead.

   Default to read-only, and consider keeping writers private
       Making attributes mutable just means more complexity to account for in
       your program. The alternative to	mutable	state is to encourage users of
       your class to simply make new objects as	needed.

       If you must make	an attribute read-write, consider making the writer a
       separate	private	method.	Narrower APIs are easy to maintain, and
       mutable state is	trouble.

       In order	to declare such	attributes, provide a private "writer"
       parameter:

	   has pizza =>	(
	       is     => 'ro',
	       isa    => 'Pizza',
	       writer => '_pizza',
	   );

   Think twice before changing an attribute's type in a	subclass
       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.

   Don't use the "initializer" feature
       Don't know what we're talking about? That's fine.

   Use Moose::Meta::Attribute::Native traits instead of	"auto_deref"
       The "auto_deref"	feature	is a bit troublesome. Directly exposing	a
       complex attribute is ugly. Instead, consider using
       Moose::Meta::Attribute::Native traits to	define an API that only
       exposes the necessary pieces of functionality.

   Always call "inner" in the most specific subclass
       When using "augment" and	"inner", we recommend that you call "inner" in
       the most	specific subclass of your hierarchy. This makes	it possible to
       subclass	further	and extend the hierarchy without changing the parents.

   Namespace your types
       Use some	sort of	namespacing convention for type	names. We recommend
       something like "MyApp::Type::Foo". We also recommend considering
       MooseX::Types.

   Do not coerce Moose built-ins directly
       If you define a coercion	for a Moose built-in like "ArrayRef", 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	/,/ ] };

   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( %{$_} ) };

   Use coercion	instead	of unions
       Consider	using a	type coercion instead of a type	union. This was
       covered in Moose::Manual::Types.

   Define all your types in one	module
       Define all your types and coercions in one module. This was also
       covered in Moose::Manual::Types.

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 "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 for MooseX extensions
       which rely on introspection to do the right thing.

AUTHORS
       o   Stevan Little <stevan.little@iinteractive.com>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@tozt.net>

       o   Shawn M Moore <code@sartak.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@weftsoar.net>

       o   Chris Prather <chris@prather.org>

       o   Matt	S Trout	<mst@shadowcat.co.uk>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2006 by Infinity Interactive, Inc.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2017-05-03   Moose::Manual::BestPractices(3)

NAME | VERSION | RECOMMENDATIONS | BENEFITS OF BEST PRACTICES | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Manual::BestPractices&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help