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

VERSION

518       This is part of Perl::Critic version 1.116.
519

AUTHOR

521       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
522

COPYRIGHT

524       Copyright (c) 2005-2011 Imaginative Software Systems.  All rights
525       reserved.
526
527       This program is free software; you can redistribute it and/or modify it
528       under the same terms as Perl itself.  The full text of this license can
529       be found in the LICENSE file included with this module.
530
531
532
533perl v5.16.3                      2014-06-09    Perl::Critic::PolicySummary(3)