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

FreeBSD Manual Pages

  
 
  

home | help
Perl::CritiPerl::CritiUseroContributedsPerlxDocumentationohibitMagicNumbers(3)

NAME
       Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers	-
       Don't use values	that don't explain themselves.

AFFILIATION
       This Policy is part of the core Perl::Critic distribution.

DESCRIPTION
       What is a "magic	number"?  A magic number is a number that appears in
       code without any	explanation; e.g.  "$bank_account_balance *= 57.492;".
       You look	at that	number and have	to wonder where	that number came from.
       Since you don't understand the significance of the number, you don't
       understand the code.

       In general, numeric literals other than 0 or 1 in should	not be used.
       Use the constant	pragma or the Readonly or Const::Fast modules to give
       a descriptive name to the number.

       There are, of course, exceptions	to when	this rule should be applied.
       One good	example	is positioning of objects in some container like
       shapes on a blueprint or	widgets	in a user interface.  In these cases,
       the significance	of a number can	readily	be determined by context.

       The maximum number of violations	per document for this policy defaults
       to 10.

   Ways	in which this module applies this rule.
       By default, this	rule is	relaxed	in that	2 is permitted to allow	for
       common things like alternation, the STDERR file handle, etc..

       Numeric literals	are allowed in "use" and "require" statements to allow
       for things like Perl version restrictions and Test::More	plans.
       Declarations of $VERSION	package	variables are permitted.  Use of
       "Readonly", "Readonly::Scalar", "Readonly::Array", and "Readonly::Hash"
       from the	Readonly module	are obviously valid, but use of
       "Readonly::Scalar1", "Readonly::Array1",	and "Readonly::Hash1" are
       specifically not	supported.

       Use of binary, exponential, hexadecimal,	octal, and version numbers,
       even for	0 and 1, outside of "use"/"require"/"Readonly" statements
       aren't permitted	(but you can change this).

       There is	a special exemption for	accessing the last element of an
       array, i.e. $x[-1].

	   $x =	0;				     # ok
	   $x =	0.0;				     # ok
	   $x =	1;				     # ok
	   $x =	1.0;				     # ok
	   $x =	1.5;				     # not ok
	   $x =	0b0				     # not ok
	   $x =	0b1				     # not ok
	   $x =	0x00				     # not ok
	   $x =	0x01				     # not ok
	   $x =	000				     # not ok
	   $x =	001				     # not ok
	   $x =	0e1				     # not ok
	   $x =	1e1				     # not ok

	   $frobnication_factor	= 42;		     # not ok
	   use constant	FROBNICATION_FACTOR => 42;   # ok

	   use 5.6.1;				     # ok
	   use Test::More plan => 57;		     # ok
	   plan	tests => 39;			     # ok
	   our $VERSION	= 0.22;			     # ok

	   $x =	$y[-1]				     # ok
	   $x =	$y[-2]				     # not ok

	   foreach my $solid (1..5) {		     # not ok
	       ...
	   }

	   use Readonly;

	   Readonly my $REGULAR_GEOMETRIC_SOLIDS => 5;

	   foreach my $solid (1..$REGULAR_GEOMETRIC_SOLIDS) {  #ok
	       ...
	   }

CONFIGURATION
       This policy has four options: "allowed_values", "allowed_types",
       "allow_to_the_right_of_a_fat_comma", and
       "constant_creator_subroutines".

   "allowed_values"
       The "allowed_values" parameter is a whitespace delimited	set of
       permitted number	values;	this does not affect the permitted formats for
       numbers.	 The defaults are equivalent to	having the following in	your
       .perlcriticrc:

	   [ValuesAndExpressions::ProhibitMagicNumbers]
	   allowed_values = 0 1	2

       Note that this policy forces the	values 0 and 1 into the	permitted
       values.	Thus, specifying no values,

	   allowed_values =

       is the same as simply listing 0 and 1:

	   allowed_values = 0 1

       The special "all_integers" value, not surprisingly, allows all integral
       values to pass, subject to the restrictions on number types.

       Ranges can be specified as two (possibly	fractional) numbers separated
       by two periods, optionally suffixed with	an increment using the Perl 6
       ":by()" syntax.	E.g.

	   allowed_values = 7..10

       will allow 0, 1,	7, 8, 9, and 10	as literal values.  Using fractional
       values like so

	   allowed_values = -3.5..-0.5:by(0.5)

       will permit -3.5, -3, -2.5, -2, -2.5, -1, -0.5, 0, and 1.
       Unsurprisingly, the increment defaults to 1, which means	that

	   allowed_values = -3.5..-0.5

       will make -3.5, -2.5, -2.5, -0.5, 0, and	1 valid.

       Ranges are not lazy, i.e. you'd better have a lot of memory available
       if you use a range of "1..1000:by(0.01)".  Also remember	that all of
       this is done using floating-point math, which means that
       "1..10:by(0.3333)" is probably not going	to be very useful.

       Specifying an upper limit that is less than the lower limit will	result
       in no values being produced by that range.  Negative increments are not
       permitted.

       Multiple	ranges are permitted.

       To put this all together, the following is a valid, though not likely
       to be used, .perlcriticrc entry:

	   [ValuesAndExpressions::ProhibitMagicNumbers]
	   allowed_values = 3.1415269 82..103 -507.4..57.8:by(0.2) all_integers

   "allowed_types"
       The "allowed_types" parameter is	a whitespace delimited set of
       subclasses of PPI::Token::Number.

       Decimal integers	are always allowed.  By	default, floating-point
       numbers are also	allowed.

       For example, to allow hexadecimal literals, you could configure this
       policy like

	   [ValuesAndExpressions::ProhibitMagicNumbers]
	   allowed_types = Hex

       but without specifying anything for "allowed_values", the allowed
       hexadecimal literals will be 0x00, 0x01,	and 0x02.  Note, also, as soon
       as you specify a	value for this parameter, you must include "Float" in
       the list	to continue to be able to use floating point literals.	This
       effect can be used to restrict literals to only decimal integers:

	   [ValuesAndExpressions::ProhibitMagicNumbers]
	   allowed_types =

       If you permit exponential notation, you automatically also allow
       floating	point values because an	exponential is a subclass of floating-
       point in	PPI.

   "allow_to_the_right_of_a_fat_comma"
       If this is set, you can put any number to the right of a	fat comma.

	   my %hash =	  ( a => 4512, b => 293	);	   # ok
	   my $hash_ref	= { a => 4512, b => 293	};	   # ok
	   some_subroutine( a => 4512, b => 293	);	   # ok

       Currently, this only means directly to the right	of the fat comma.  By
       default,	this value is true.

   "constant_creator_subroutines"
       This parameter allows you to specify the	names of subroutines that
       create constants, in addition to	"Readonly", "Const::Fast", and
       friends.	 For example, if you use a custom "Const::Fast"-like module
       that supports a "create_constant" subroutine to create constants, you
       could add something like	the following to your .perlcriticrc:

	   [ValuesAndExpressions::ProhibitMagicNumbers]
	   constant_creator_subroutines	= create_constant

       If you have more	than one name to add, separate them by whitespace.

       The subroutine name should appear exactly as it is in your code.	 For
       example,	if your	code does not import the creating subroutine
       subroutine, you would need to configure this policy as something	like

	   [ValuesAndExpressions::ProhibitMagicNumbers]
	   constant_creator_subroutines	= create_constant Constant::Create::create_constant

BUGS
       There is	currently no way to permit version numbers in regular code,
       even if you include them	in the "allowed_types".	 Some may actually
       consider	this a feature.

AUTHOR
       Elliot Shank "<perl@galumph.com>"

COPYRIGHT
       Copyright (c) 2006-2011 Elliot Shank.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  The full text of this license can
       be found	in the LICENSE file included with this module.

perl v5.24.Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers(3)

NAME | AFFILIATION | DESCRIPTION | CONFIGURATION | BUGS | AUTHOR | COPYRIGHT

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

home | help