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 "any" from "List::Util", "List::SomeUtils", or "List::MoreUtils"
25       instead of "grep" in boolean context. [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 parent" 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::ProhibitBarewordDirHandles
184       Write "opendir my $dh, $dirname;" instead of "opendir DH, $dirname;".
185       [Default severity 5]
186
187   InputOutput::ProhibitBarewordFileHandles
188       Write "open my $fh, q{<}, $filename;" instead of "open FH, q{<},
189       $filename;". [Default severity 5]
190
191   InputOutput::ProhibitExplicitStdin
192       Use "<>" or "<ARGV>" or a prompting module instead of "<STDIN>".
193       [Default severity 4]
194
195   InputOutput::ProhibitInteractiveTest
196       Use prompt() instead of -t. [Default severity 5]
197
198   InputOutput::ProhibitJoinedReadline
199       Use "local $/ = undef" or Path::Tiny instead of joined readline.
200       [Default severity 3]
201
202   InputOutput::ProhibitOneArgSelect
203       Never write select($fh). [Default severity 4]
204
205   InputOutput::ProhibitReadlineInForLoop
206       Write "while( $line = <> ){...}" instead of "for(<>){...}". [Default
207       severity 4]
208
209   InputOutput::ProhibitTwoArgOpen
210       Write "open $fh, q{<}, $filename;" instead of "open $fh,
211       "<$filename";". [Default severity 5]
212
213   InputOutput::RequireBracedFileHandleWithPrint
214       Write "print {$FH} $foo, $bar;" instead of "print $FH $foo, $bar;".
215       [Default severity 1]
216
217   InputOutput::RequireBriefOpen
218       Close filehandles as soon as possible after opening them. [Default
219       severity 4]
220
221   InputOutput::RequireCheckedClose
222       Write "my $error = close $fh;" instead of "close $fh;". [Default
223       severity 2]
224
225   InputOutput::RequireCheckedOpen
226       Write "my $error = open $fh, $mode, $filename;" instead of "open $fh,
227       $mode, $filename;". [Default severity 3]
228
229   InputOutput::RequireCheckedSyscalls
230       Return value of flagged function ignored. [Default severity 1]
231
232   InputOutput::RequireEncodingWithUTF8Layer
233       Write "open $fh, q{<:encoding(UTF-8)}, $filename;" instead of "open
234       $fh, q{<:utf8}, $filename;". [Default severity 5]
235
236   Miscellanea::ProhibitFormats
237       Do not use "format". [Default severity 3]
238
239   Miscellanea::ProhibitTies
240       Do not use "tie". [Default severity 2]
241
242   Miscellanea::ProhibitUnrestrictedNoCritic
243       Forbid a bare "## no critic" [Default severity 3]
244
245   Miscellanea::ProhibitUselessNoCritic
246       Remove ineffective "## no critic" annotations. [Default severity 2]
247
248   Modules::ProhibitAutomaticExportation
249       Export symbols via @EXPORT_OK or %EXPORT_TAGS instead of @EXPORT.
250       [Default severity 4]
251
252   Modules::ProhibitConditionalUseStatements
253       Avoid putting conditional logic around compile-time includes. [Default
254       severity 3]
255
256   Modules::ProhibitEvilModules
257       Ban modules that aren't blessed by your shop. [Default severity 5]
258
259   Modules::ProhibitExcessMainComplexity
260       Minimize complexity in code that is outside of subroutines. [Default
261       severity 3]
262
263   Modules::ProhibitMultiplePackages
264       Put packages (especially subclasses) in separate files. [Default
265       severity 4]
266
267   Modules::RequireBarewordIncludes
268       Write "require Module" instead of "require 'Module.pm'". [Default
269       severity 5]
270
271   Modules::RequireEndWithOne
272       End each module with an explicitly "1;" instead of some funky
273       expression. [Default severity 4]
274
275   Modules::RequireExplicitPackage
276       Always make the "package" explicit. [Default severity 4]
277
278   Modules::RequireFilenameMatchesPackage
279       Package declaration must match filename. [Default severity 5]
280
281   Modules::RequireNoMatchVarsWithUseEnglish
282       "use English" must be passed a "-no_match_vars" argument. [Default
283       severity 2]
284
285   Modules::RequireVersionVar
286       Give every module a $VERSION number. [Default severity 2]
287
288   NamingConventions::Capitalization
289       Distinguish different program components by case. [Default severity 1]
290
291   NamingConventions::ProhibitAmbiguousNames
292       Don't use vague variable or subroutine names like 'last' or 'record'.
293       [Default severity 3]
294
295   Objects::ProhibitIndirectSyntax
296       Prohibit indirect object call syntax. [Default severity 4]
297
298   References::ProhibitDoubleSigils
299       Write "@{ $array_ref }" instead of @$array_ref. [Default severity 2]
300
301   RegularExpressions::ProhibitCaptureWithoutTest
302       Capture variable used outside conditional. [Default severity 3]
303
304   RegularExpressions::ProhibitComplexRegexes
305       Split long regexps into smaller "qr//" chunks. [Default severity 3]
306
307   RegularExpressions::ProhibitEnumeratedClasses
308       Use named character classes instead of explicit character lists.
309       [Default severity 1]
310
311   RegularExpressions::ProhibitEscapedMetacharacters
312       Use character classes for literal meta-characters instead of escapes.
313       [Default severity 1]
314
315   RegularExpressions::ProhibitFixedStringMatches
316       Use "eq" or hash instead of fixed-pattern regexps. [Default severity 2]
317
318   RegularExpressions::ProhibitSingleCharAlternation
319       Use "[abc]" instead of "a|b|c". [Default severity 1]
320
321   RegularExpressions::ProhibitUnusedCapture
322       Only use a capturing group if you plan to use the captured value.
323       [Default severity 3]
324
325   RegularExpressions::ProhibitUnusualDelimiters
326       Use only "//" or "{}" to delimit regexps. [Default severity 1]
327
328   RegularExpressions::ProhibitUselessTopic
329       Don't use $_ to match against regexes. [Default severity 2]
330
331   RegularExpressions::RequireBracesForMultiline
332       Use "{" and "}" to delimit multi-line regexps. [Default severity 1]
333
334   RegularExpressions::RequireDotMatchAnything
335       Always use the "/s" modifier with regular expressions. [Default
336       severity 2]
337
338   RegularExpressions::RequireExtendedFormatting
339       Always use the "/x" modifier with regular expressions. [Default
340       severity 3]
341
342   RegularExpressions::RequireLineBoundaryMatching
343       Always use the "/m" modifier with regular expressions. [Default
344       severity 2]
345
346   Subroutines::ProhibitAmpersandSigils
347       Don't call functions with a leading ampersand sigil. [Default severity
348       2]
349
350   Subroutines::ProhibitBuiltinHomonyms
351       Don't declare your own "open" function. [Default severity 4]
352
353   Subroutines::ProhibitExcessComplexity
354       Minimize complexity by factoring code into smaller subroutines.
355       [Default severity 3]
356
357   Subroutines::ProhibitExplicitReturnUndef
358       Return failure with bare "return" instead of "return undef". [Default
359       severity 5]
360
361   Subroutines::ProhibitManyArgs
362       Too many arguments. [Default severity 3]
363
364   Subroutines::ProhibitNestedSubs
365       "sub never { sub correct {} }". [Default severity 5]
366
367   Subroutines::ProhibitReturnSort
368       Behavior of "sort" is not defined if called in scalar context. [Default
369       severity 5]
370
371   Subroutines::ProhibitSubroutinePrototypes
372       Don't write "sub my_function (@@) {}". [Default severity 5]
373
374   Subroutines::ProhibitUnusedPrivateSubroutines
375       Prevent unused private subroutines. [Default severity 3]
376
377   Subroutines::ProtectPrivateSubs
378       Prevent access to private subs in other packages. [Default severity 3]
379
380   Subroutines::RequireArgUnpacking
381       Always unpack @_ first. [Default severity 4]
382
383   Subroutines::RequireFinalReturn
384       End every path through a subroutine with an explicit "return"
385       statement. [Default severity 4]
386
387   TestingAndDebugging::ProhibitNoStrict
388       Prohibit various flavors of "no strict". [Default severity 5]
389
390   TestingAndDebugging::ProhibitNoWarnings
391       Prohibit various flavors of "no warnings". [Default severity 4]
392
393   TestingAndDebugging::ProhibitProlongedStrictureOverride
394       Don't turn off strict for large blocks of code. [Default severity 4]
395
396   TestingAndDebugging::RequireTestLabels
397       Tests should all have labels. [Default severity 3]
398
399   TestingAndDebugging::RequireUseStrict
400       Always "use strict". [Default severity 5]
401
402   TestingAndDebugging::RequireUseWarnings
403       Always "use warnings". [Default severity 4]
404
405   ValuesAndExpressions::ProhibitCommaSeparatedStatements
406       Don't use the comma operator as a statement separator. [Default
407       severity 4]
408
409   ValuesAndExpressions::ProhibitComplexVersion
410       Prohibit version values from outside the module. [Default severity 3]
411
412   ValuesAndExpressions::ProhibitConstantPragma
413       Don't "use constant FOO => 15". [Default severity 4]
414
415   ValuesAndExpressions::ProhibitEmptyQuotes
416       Write "q{}" instead of ''. [Default severity 2]
417
418   ValuesAndExpressions::ProhibitEscapedCharacters
419       Write "\N{DELETE}" instead of "\x7F", etc. [Default severity 2]
420
421   ValuesAndExpressions::ProhibitImplicitNewlines
422       Use concatenation or HEREDOCs instead of literal line breaks in
423       strings. [Default severity 3]
424
425   ValuesAndExpressions::ProhibitInterpolationOfLiterals
426       Always use single quotes for literal strings. [Default severity 1]
427
428   ValuesAndExpressions::ProhibitLeadingZeros
429       Write oct(755) instead of 0755. [Default severity 5]
430
431   ValuesAndExpressions::ProhibitLongChainsOfMethodCalls
432       Long chains of method calls indicate tightly coupled code. [Default
433       severity 2]
434
435   ValuesAndExpressions::ProhibitMagicNumbers
436       Don't use values that don't explain themselves. [Default severity 2]
437
438   ValuesAndExpressions::ProhibitMismatchedOperators
439       Don't mix numeric operators with string operands, or vice-versa.
440       [Default severity 3]
441
442   ValuesAndExpressions::ProhibitMixedBooleanOperators
443       Write " !$foo && $bar || $baz " instead of " not $foo && $bar or $baz".
444       [Default severity 4]
445
446   ValuesAndExpressions::ProhibitNoisyQuotes
447       Use "q{}" or "qq{}" instead of quotes for awkward-looking strings.
448       [Default severity 2]
449
450   ValuesAndExpressions::ProhibitQuotesAsQuotelikeOperatorDelimiters
451       Don't use quotes ("'", """, "`") as delimiters for the quote-like
452       operators. [Default severity 3]
453
454   ValuesAndExpressions::ProhibitSpecialLiteralHeredocTerminator
455       Don't write " print <<'__END__' ". [Default severity 3]
456
457   ValuesAndExpressions::ProhibitVersionStrings
458       Don't use strings like "v1.4" or 1.4.5 when including other modules.
459       [Default severity 3]
460
461   ValuesAndExpressions::RequireConstantVersion
462       Require $VERSION to be a constant rather than a computed value.
463       [Default severity 2]
464
465   ValuesAndExpressions::RequireInterpolationOfMetachars
466       Warns that you might have used single quotes when you really wanted
467       double-quotes. [Default severity 1]
468
469   ValuesAndExpressions::RequireNumberSeparators
470       Write " 141_234_397.0145 " instead of  141234397.0145 . [Default
471       severity 2]
472
473   ValuesAndExpressions::RequireQuotedHeredocTerminator
474       Write " print <<'THE_END' " or " print <<"THE_END" ". [Default severity
475       3]
476
477   ValuesAndExpressions::RequireUpperCaseHeredocTerminator
478       Write " <<'THE_END'; " instead of " <<'theEnd'; ". [Default severity 2]
479
480   Variables::ProhibitAugmentedAssignmentInDeclaration
481       Do not write " my $foo .= 'bar'; ". [Default severity 4]
482
483   Variables::ProhibitConditionalDeclarations
484       Do not write " my $foo = $bar if $baz; ". [Default severity 5]
485
486   Variables::ProhibitEvilVariables
487       Ban variables that aren't blessed by your shop. [Default severity 5]
488
489   Variables::ProhibitLocalVars
490       Use "my" instead of "local", except when you have to. [Default severity
491       2]
492
493   Variables::ProhibitMatchVars
494       Avoid "$`", $&, "$'" and their English equivalents. [Default severity
495       4]
496
497   Variables::ProhibitPackageVars
498       Eliminate globals declared with "our" or "use vars". [Default severity
499       3]
500
501   Variables::ProhibitPerl4PackageNames
502       Use double colon (::) to separate package name components instead of
503       single quotes ('). [Default severity 2]
504
505   Variables::ProhibitPunctuationVars
506       Write $EVAL_ERROR instead of $@. [Default severity 2]
507
508   Variables::ProhibitReusedNames
509       Do not reuse a variable name in a lexical scope [Default severity 3]
510
511   Variables::ProhibitUnusedVariables
512       Don't ask for storage you don't need. [Default severity 3]
513
514   Variables::ProtectPrivateVars
515       Prevent access to private vars in other packages. [Default severity 3]
516
517   Variables::RequireInitializationForLocalVars
518       Write "local $foo = $bar;" instead of just "local $foo;". [Default
519       severity 3]
520
521   Variables::RequireLexicalLoopIterators
522       Write "for my $element (@list) {...}" instead of "for $element (@list)
523       {...}". [Default severity 5]
524
525   Variables::RequireLocalizedPunctuationVars
526       Magic variables should be assigned as "local". [Default severity 4]
527
528   Variables::RequireNegativeIndices
529       Negative array index should be used. [Default severity 4]
530

VERSION

532       This is part of Perl::Critic version 1.126.
533

AUTHOR

535       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
536

COPYRIGHT

538       Copyright (c) 2005-2011 Imaginative Software Systems.  All rights
539       reserved.
540
541       This program is free software; you can redistribute it and/or modify it
542       under the same terms as Perl itself.  The full text of this license can
543       be found in the LICENSE file included with this module.
544
545
546
547perl v5.36.0                      2023-03-05    Perl::Critic::PolicySummary(3)