Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers - Don't use values that don't explain themselves.
This Policy is part of the core Perl::Critic distribution.
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 module 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.
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
...
}
This policy has two options: allowed_values and allowed_types.
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.
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.
Elliot Shank <perl@galumph.com>
Copyright (c) 2006-2008 Elliot Shank. All rights reserved.
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.