1Perl::Critic::PolicySumUmsaerry(C3o)ntributed Perl DocumPeenrtla:t:iCornitic::PolicySummary(3)
2
3
4

NAME

6       Perl::Critic::PolicySummary - Descriptions of the Policy modules
7       included with Perl::Critic itself.
8

DESCRIPTION

10       The following Policy modules are distributed with Perl::Critic. (There
11       are additional Policies that can be found in add-on distributions.)
12       The Policy modules have been categorized according to the table of
13       contents in Damian Conway's book Perl Best Practices. Since most coding
14       standards take the form "do this..." or "don't do that...", I have
15       adopted the convention of naming each module "RequireSomething" or
16       "ProhibitSomething".  Each Policy is listed here with its default
17       severity.  If you don't agree with the default severity, you can change
18       it in your .perlcriticrc file (try "perlcritic --profile-proto" for a
19       starting version).  See the documentation of each module for its
20       specific details.
21

POLICIES

23   BuiltinFunctions::ProhibitBooleanGrep
24       Use "List::MoreUtils::any" instead of "grep" in boolean context.
25       [Default severity 2]
26
27   BuiltinFunctions::ProhibitComplexMappings
28       Map blocks should have a single statement. [Default severity 3]
29
30   BuiltinFunctions::ProhibitLvalueSubstr
31       Use 4-argument "substr" instead of writing "substr($foo, 2, 6) = $bar".
32       [Default severity 3]
33
34   BuiltinFunctions::ProhibitReverseSortBlock
35       Forbid $b before $a in sort blocks. [Default severity 1]
36
37   BuiltinFunctions::ProhibitShiftRef
38       Prohibit "\shift" in code [Default severity 3]
39
40   BuiltinFunctions::ProhibitSleepViaSelect
41       Use Time::HiRes instead of something like "select(undef, undef, undef,
42       .05)". [Default severity 5]
43
44   BuiltinFunctions::ProhibitStringyEval
45       Write "eval { my $foo; bar($foo) }" instead of "eval "my $foo;
46       bar($foo);"". [Default severity 5]
47
48   BuiltinFunctions::ProhibitStringySplit
49       Write "split /-/, $string" instead of "split '-', $string". [Default
50       severity 2]
51
52   BuiltinFunctions::ProhibitUniversalCan
53       Write "eval { $foo->can($name) }" instead of "UNIVERSAL::can($foo,
54       $name)". [Default severity 3]
55
56   BuiltinFunctions::ProhibitUniversalIsa
57       Write "eval { $foo->isa($pkg) }" instead of "UNIVERSAL::isa($foo,
58       $pkg)". [Default severity 3]
59
60   BuiltinFunctions::ProhibitUselessTopic
61       Don't pass $_ to built-in functions that assume it, or to most filetest
62       operators. [Default severity 2]
63
64   BuiltinFunctions::ProhibitVoidGrep
65       Don't use "grep" in void contexts. [Default severity 3]
66
67   BuiltinFunctions::ProhibitVoidMap
68       Don't use "map" in void contexts. [Default severity 3]
69
70   BuiltinFunctions::RequireBlockGrep
71       Write "grep { /$pattern/ } @list" instead of "grep /$pattern/, @list".
72       [Default severity 4]
73
74   BuiltinFunctions::RequireBlockMap
75       Write "map { /$pattern/ } @list" instead of "map /$pattern/, @list".
76       [Default severity 4]
77
78   BuiltinFunctions::RequireGlobFunction
79       Use "glob q{*}" instead of <*>. [Default severity 5]
80
81   BuiltinFunctions::RequireSimpleSortBlock
82       Sort blocks should have a single statement. [Default severity 3]
83
84   ClassHierarchies::ProhibitAutoloading
85       AUTOLOAD methods should be avoided. [Default severity 3]
86
87   ClassHierarchies::ProhibitExplicitISA
88       Employ "use base" instead of @ISA. [Default severity 3]
89
90   ClassHierarchies::ProhibitOneArgBless
91       Write "bless {}, $class;" instead of just "bless {};". [Default
92       severity 5]
93
94   CodeLayout::ProhibitHardTabs
95       Use spaces instead of tabs. [Default severity 3]
96
97   CodeLayout::ProhibitParensWithBuiltins
98       Write "open $handle, $path" instead of "open($handle, $path)". [Default
99       severity 1]
100
101   CodeLayout::ProhibitQuotedWordLists
102       Write "qw(foo bar baz)" instead of "('foo', 'bar', 'baz')". [Default
103       severity 2]
104
105   CodeLayout::ProhibitTrailingWhitespace
106       Don't use whitespace at the end of lines. [Default severity 1]
107
108   CodeLayout::RequireConsistentNewlines
109       Use the same newline through the source. [Default severity 4]
110
111   CodeLayout::RequireTidyCode
112       Must run code through perltidy. [Default severity 1]
113
114   CodeLayout::RequireTrailingCommas
115       Put a comma at the end of every multi-line list declaration, including
116       the last one. [Default severity 1]
117
118   ControlStructures::ProhibitCStyleForLoops
119       Write "for(0..20)" instead of "for($i=0; $i<=20; $i++)". [Default
120       severity 2]
121
122   ControlStructures::ProhibitCascadingIfElse
123       Don't write long "if-elsif-elsif-elsif-elsif...else" chains. [Default
124       severity 3]
125
126   ControlStructures::ProhibitDeepNests
127       Don't write deeply nested loops and conditionals. [Default severity 3]
128
129   ControlStructures::ProhibitLabelsWithSpecialBlockNames
130       Don't use labels that are the same as the special block names. [Default
131       severity 4]
132
133   ControlStructures::ProhibitMutatingListFunctions
134       Don't modify $_ in list functions. [Default severity 5]
135
136   ControlStructures::ProhibitNegativeExpressionsInUnlessAndUntilConditions
137       Don't use operators like "not", "!~", and "le" within "until" and
138       "unless". [Default severity 3]
139
140   ControlStructures::ProhibitPostfixControls
141       Write "if($condition){ do_something() }" instead of "do_something() if
142       $condition". [Default severity 2]
143
144   ControlStructures::ProhibitUnlessBlocks
145       Write "if(! $condition)" instead of "unless($condition)". [Default
146       severity 2]
147
148   ControlStructures::ProhibitUnreachableCode
149       Don't write code after an unconditional "die, exit, or next". [Default
150       severity 4]
151
152   ControlStructures::ProhibitUntilBlocks
153       Write "while(! $condition)" instead of "until($condition)". [Default
154       severity 2]
155
156   ControlStructures::ProhibitYadaOperator
157       Never use "..." in production code. [Default severity 4]
158
159   Documentation::PodSpelling
160       Check your spelling. [Default severity 1]
161
162   Documentation::RequirePackageMatchesPodName
163       The "=head1 NAME" section should match the package. [Default severity
164       1]
165
166   Documentation::RequirePodAtEnd
167       All POD should be after "__END__". [Default severity 1]
168
169   Documentation::RequirePodSections
170       Organize your POD into the customary sections. [Default severity 2]
171
172   ErrorHandling::RequireCarping
173       Use functions from Carp instead of "warn" or "die". [Default severity
174       3]
175
176   ErrorHandling::RequireCheckingReturnValueOfEval
177       You can't depend upon the value of $@/$EVAL_ERROR to tell whether an
178       "eval" failed. [Default severity 3]
179
180   InputOutput::ProhibitBacktickOperators
181       Discourage stuff like "@files = `ls $directory`". [Default severity 3]
182
183   InputOutput::ProhibitBarewordFileHandles
184       Write "open my $fh, q{<}, $filename;" instead of "open FH, q{<},
185       $filename;". [Default severity 5]
186
187   InputOutput::ProhibitExplicitStdin
188       Use "<>" or "<ARGV>" or a prompting module instead of "<STDIN>".
189       [Default severity 4]
190
191   InputOutput::ProhibitInteractiveTest
192       Use prompt() instead of -t. [Default severity 5]
193
194   InputOutput::ProhibitJoinedReadline
195       Use "local $/ = undef" or Path::Tiny instead of joined readline.
196       [Default severity 3]
197
198   InputOutput::ProhibitOneArgSelect
199       Never write "select($fh)". [Default severity 4]
200
201   InputOutput::ProhibitReadlineInForLoop
202       Write "while( $line = <> ){...}" instead of "for(<>){...}". [Default
203       severity 4]
204
205   InputOutput::ProhibitTwoArgOpen
206       Write "open $fh, q{<}, $filename;" instead of "open $fh,
207       "<$filename";". [Default severity 5]
208
209   InputOutput::RequireBracedFileHandleWithPrint
210       Write "print {$FH} $foo, $bar;" instead of "print $FH $foo, $bar;".
211       [Default severity 1]
212
213   InputOutput::RequireBriefOpen
214       Close filehandles as soon as possible after opening them. [Default
215       severity 4]
216
217   InputOutput::RequireCheckedClose
218       Write "my $error = close $fh;" instead of "close $fh;". [Default
219       severity 2]
220
221   InputOutput::RequireCheckedOpen
222       Write "my $error = open $fh, $mode, $filename;" instead of "open $fh,
223       $mode, $filename;". [Default severity 3]
224
225   InputOutput::RequireCheckedSyscalls
226       Return value of flagged function ignored. [Default severity 1]
227
228   InputOutput::RequireEncodingWithUTF8Layer
229       Write "open $fh, q{<:encoding(UTF-8)}, $filename;" instead of "open
230       $fh, q{<:utf8}, $filename;". [Default severity 5]
231
232   Miscellanea::ProhibitFormats
233       Do not use "format". [Default severity 3]
234
235   Miscellanea::ProhibitTies
236       Do not use "tie". [Default severity 2]
237
238   Miscellanea::ProhibitUnrestrictedNoCritic
239       Forbid a bare "## no critic" [Default severity 3]
240
241   Miscellanea::ProhibitUselessNoCritic
242       Remove ineffective "## no critic" annotations. [Default severity 2]
243
244   Modules::ProhibitAutomaticExportation
245       Export symbols via @EXPORT_OK or %EXPORT_TAGS instead of @EXPORT.
246       [Default severity 4]
247
248   Modules::ProhibitConditionalUseStatements
249       Avoid putting conditional logic around compile-time includes. [Default
250       severity 3]
251
252   Modules::ProhibitEvilModules
253       Ban modules that aren't blessed by your shop. [Default severity 5]
254
255   Modules::ProhibitExcessMainComplexity
256       Minimize complexity in code that is outside of subroutines. [Default
257       severity 3]
258
259   Modules::ProhibitMultiplePackages
260       Put packages (especially subclasses) in separate files. [Default
261       severity 4]
262
263   Modules::RequireBarewordIncludes
264       Write "require Module" instead of "require 'Module.pm'". [Default
265       severity 5]
266
267   Modules::RequireEndWithOne
268       End each module with an explicitly "1;" instead of some funky
269       expression. [Default severity 4]
270
271   Modules::RequireExplicitPackage
272       Always make the "package" explicit. [Default severity 4]
273
274   Modules::RequireFilenameMatchesPackage
275       Package declaration must match filename. [Default severity 5]
276
277   Modules::RequireNoMatchVarsWithUseEnglish
278       "use English" must be passed a "-no_match_vars" argument. [Default
279       severity 2]
280
281   Modules::RequireVersionVar
282       Give every module a $VERSION number. [Default severity 2]
283
284   NamingConventions::Capitalization
285       Distinguish different program components by case. [Default severity 1]
286
287   NamingConventions::ProhibitAmbiguousNames
288       Don't use vague variable or subroutine names like 'last' or 'record'.
289       [Default severity 3]
290
291   Objects::ProhibitIndirectSyntax
292       Prohibit indirect object call syntax. [Default severity 4]
293
294   References::ProhibitDoubleSigils
295       Write "@{ $array_ref }" instead of @$array_ref. [Default severity 2]
296
297   RegularExpressions::ProhibitCaptureWithoutTest
298       Capture variable used outside conditional. [Default severity 3]
299
300   RegularExpressions::ProhibitComplexRegexes
301       Split long regexps into smaller "qr//" chunks. [Default severity 3]
302
303   RegularExpressions::ProhibitEnumeratedClasses
304       Use named character classes instead of explicit character lists.
305       [Default severity 1]
306
307   RegularExpressions::ProhibitEscapedMetacharacters
308       Use character classes for literal meta-characters instead of escapes.
309       [Default severity 1]
310
311   RegularExpressions::ProhibitFixedStringMatches
312       Use "eq" or hash instead of fixed-pattern regexps. [Default severity 2]
313
314   RegularExpressions::ProhibitSingleCharAlternation
315       Use "[abc]" instead of "a|b|c". [Default severity 1]
316
317   RegularExpressions::ProhibitUnusedCapture
318       Only use a capturing group if you plan to use the captured value.
319       [Default severity 3]
320
321   RegularExpressions::ProhibitUnusualDelimiters
322       Use only "//" or "{}" to delimit regexps. [Default severity 1]
323
324   RegularExpressions::ProhibitUselessTopic
325       Don't use $_ to match against regexes. [Default severity 2]
326
327   RegularExpressions::RequireBracesForMultiline
328       Use "{" and "}" to delimit multi-line regexps. [Default severity 1]
329
330   RegularExpressions::RequireDotMatchAnything
331       Always use the "/s" modifier with regular expressions. [Default
332       severity 2]
333
334   RegularExpressions::RequireExtendedFormatting
335       Always use the "/x" modifier with regular expressions. [Default
336       severity 3]
337
338   RegularExpressions::RequireLineBoundaryMatching
339       Always use the "/m" modifier with regular expressions. [Default
340       severity 2]
341
342   Subroutines::ProhibitAmpersandSigils
343       Don't call functions with a leading ampersand sigil. [Default severity
344       2]
345
346   Subroutines::ProhibitBuiltinHomonyms
347       Don't declare your own "open" function. [Default severity 4]
348
349   Subroutines::ProhibitExcessComplexity
350       Minimize complexity by factoring code into smaller subroutines.
351       [Default severity 3]
352
353   Subroutines::ProhibitExplicitReturnUndef
354       Return failure with bare "return" instead of "return undef". [Default
355       severity 5]
356
357   Subroutines::ProhibitManyArgs
358       Too many arguments. [Default severity 3]
359
360   Subroutines::ProhibitNestedSubs
361       "sub never { sub correct {} }". [Default severity 5]
362
363   Subroutines::ProhibitReturnSort
364       Behavior of "sort" is not defined if called in scalar context. [Default
365       severity 5]
366
367   Subroutines::ProhibitSubroutinePrototypes
368       Don't write "sub my_function (@@) {}". [Default severity 5]
369
370   Subroutines::ProhibitUnusedPrivateSubroutines
371       Prevent unused private subroutines. [Default severity 3]
372
373   Subroutines::ProtectPrivateSubs
374       Prevent access to private subs in other packages. [Default severity 3]
375
376   Subroutines::RequireArgUnpacking
377       Always unpack @_ first. [Default severity 4]
378
379   Subroutines::RequireFinalReturn
380       End every path through a subroutine with an explicit "return"
381       statement. [Default severity 4]
382
383   TestingAndDebugging::ProhibitNoStrict
384       Prohibit various flavors of "no strict". [Default severity 5]
385
386   TestingAndDebugging::ProhibitNoWarnings
387       Prohibit various flavors of "no warnings". [Default severity 4]
388
389   TestingAndDebugging::ProhibitProlongedStrictureOverride
390       Don't turn off strict for large blocks of code. [Default severity 4]
391
392   TestingAndDebugging::RequireTestLabels
393       Tests should all have labels. [Default severity 3]
394
395   TestingAndDebugging::RequireUseStrict
396       Always "use strict". [Default severity 5]
397
398   TestingAndDebugging::RequireUseWarnings
399       Always "use warnings". [Default severity 4]
400
401   ValuesAndExpressions::ProhibitCommaSeparatedStatements
402       Don't use the comma operator as a statement separator. [Default
403       severity 4]
404
405   ValuesAndExpressions::ProhibitComplexVersion
406       Prohibit version values from outside the module. [Default severity 3]
407
408   ValuesAndExpressions::ProhibitConstantPragma
409       Don't "use constant FOO => 15". [Default severity 4]
410
411   ValuesAndExpressions::ProhibitEmptyQuotes
412       Write "q{}" instead of ''. [Default severity 2]
413
414   ValuesAndExpressions::ProhibitEscapedCharacters
415       Write "\N{DELETE}" instead of "\x7F", etc. [Default severity 2]
416
417   ValuesAndExpressions::ProhibitImplicitNewlines
418       Use concatenation or HEREDOCs instead of literal line breaks in
419       strings. [Default severity 3]
420
421   ValuesAndExpressions::ProhibitInterpolationOfLiterals
422       Always use single quotes for literal strings. [Default severity 1]
423
424   ValuesAndExpressions::ProhibitLeadingZeros
425       Write "oct(755)" instead of 0755. [Default severity 5]
426
427   ValuesAndExpressions::ProhibitLongChainsOfMethodCalls
428       Long chains of method calls indicate tightly coupled code. [Default
429       severity 2]
430
431   ValuesAndExpressions::ProhibitMagicNumbers
432       Don't use values that don't explain themselves. [Default severity 2]
433
434   ValuesAndExpressions::ProhibitMismatchedOperators
435       Don't mix numeric operators with string operands, or vice-versa.
436       [Default severity 3]
437
438   ValuesAndExpressions::ProhibitMixedBooleanOperators
439       Write " !$foo && $bar || $baz " instead of " not $foo && $bar or $baz".
440       [Default severity 4]
441
442   ValuesAndExpressions::ProhibitNoisyQuotes
443       Use "q{}" or "qq{}" instead of quotes for awkward-looking strings.
444       [Default severity 2]
445
446   ValuesAndExpressions::ProhibitQuotesAsQuotelikeOperatorDelimiters
447       Don't use quotes ("'", """, "`") as delimiters for the quote-like
448       operators. [Default severity 3]
449
450   ValuesAndExpressions::ProhibitSpecialLiteralHeredocTerminator
451       Don't write " print <<'__END__' ". [Default severity 3]
452
453   ValuesAndExpressions::ProhibitVersionStrings
454       Don't use strings like "v1.4" or 1.4.5 when including other modules.
455       [Default severity 3]
456
457   ValuesAndExpressions::RequireConstantVersion
458       Require $VERSION to be a constant rather than a computed value.
459       [Default severity 2]
460
461   ValuesAndExpressions::RequireInterpolationOfMetachars
462       Warns that you might have used single quotes when you really wanted
463       double-quotes. [Default severity 1]
464
465   ValuesAndExpressions::RequireNumberSeparators
466       Write " 141_234_397.0145 " instead of  141234397.0145 . [Default
467       severity 2]
468
469   ValuesAndExpressions::RequireQuotedHeredocTerminator
470       Write " print <<'THE_END' " or " print <<"THE_END" ". [Default severity
471       3]
472
473   ValuesAndExpressions::RequireUpperCaseHeredocTerminator
474       Write " <<'THE_END'; " instead of " <<'theEnd'; ". [Default severity 2]
475
476   Variables::ProhibitAugmentedAssignmentInDeclaration
477       Do not write " my $foo .= 'bar'; ". [Default severity 4]
478
479   Variables::ProhibitConditionalDeclarations
480       Do not write " my $foo = $bar if $baz; ". [Default severity 5]
481
482   Variables::ProhibitEvilVariables
483       Ban variables that aren't blessed by your shop. [Default severity 5]
484
485   Variables::ProhibitLocalVars
486       Use "my" instead of "local", except when you have to. [Default severity
487       2]
488
489   Variables::ProhibitMatchVars
490       Avoid "$`", $&, "$'" and their English equivalents. [Default severity
491       4]
492
493   Variables::ProhibitPackageVars
494       Eliminate globals declared with "our" or "use vars". [Default severity
495       3]
496
497   Variables::ProhibitPerl4PackageNames
498       Use double colon (::) to separate package name components instead of
499       single quotes ('). [Default severity 2]
500
501   Variables::ProhibitPunctuationVars
502       Write $EVAL_ERROR instead of $@. [Default severity 2]
503
504   Variables::ProhibitReusedNames
505       Do not reuse a variable name in a lexical scope [Default severity 3]
506
507   Variables::ProhibitUnusedVariables
508       Don't ask for storage you don't need. [Default severity 3]
509
510   Variables::ProtectPrivateVars
511       Prevent access to private vars in other packages. [Default severity 3]
512
513   Variables::RequireInitializationForLocalVars
514       Write "local $foo = $bar;" instead of just "local $foo;". [Default
515       severity 3]
516
517   Variables::RequireLexicalLoopIterators
518       Write "for my $element (@list) {...}" instead of "for $element (@list)
519       {...}". [Default severity 5]
520
521   Variables::RequireLocalizedPunctuationVars
522       Magic variables should be assigned as "local". [Default severity 4]
523
524   Variables::RequireNegativeIndices
525       Negative array index should be used. [Default severity 4]
526

VERSION

528       This is part of Perl::Critic version 1.126.
529

AUTHOR

531       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
532

COPYRIGHT

534       Copyright (c) 2005-2011 Imaginative Software Systems.  All rights
535       reserved.
536
537       This program is free software; you can redistribute it and/or modify it
538       under the same terms as Perl itself.  The full text of this license can
539       be found in the LICENSE file included with this module.
540
541
542
543perl v5.34.0                      2021-07-22    Perl::Critic::PolicySummary(3)