Login
Bump version number to 1.07.
[gknop/Perl-Critic.git] / README
CommitLineData
b9e35135
JRT
1NAME
2 Perl::Critic - Critique Perl source code for best-practices
3
4SYNOPSIS
5 use Perl::Critic;
6 my $file = shift;
7 my $critic = Perl::Critic->new();
8 my @violations = $critic->critique($file);
9 print @violations;
10
11DESCRIPTION
12 Perl::Critic is an extensible framework for creating and applying coding
13 standards to Perl source code. Essentially, it is a static source code
14 analysis engine. Perl::Critic is distributed with a number of
15 Perl::Critic::Policy modules that attempt to enforce various coding
16 guidelines. Most Policy modules are based on Damian Conway's book Perl
17 Best Practices. However, Perl::Critic is not limited to PBP and will
18 even support Policies that contradict Conway. You can enable, disable,
19 and customize those Polices through the Perl::Critic interface. You can
20 also create new Policy modules that suit your own tastes.
21
b4c7e33c
JRT
22 For a command-line interface to Perl::Critic, see the documentation for
23 perlcritic. If you want to integrate Perl::Critic with your build
24 process, Test::Perl::Critic provides an interface that is suitable for
25 test scripts. For the ultimate convenience (at the expense of some
26 flexibility) see the criticism pragma.
b9e35135
JRT
27
28 Win32 and ActivePerl users can find PPM distributions of Perl::Critic at
29 <http://theoryx5.uwinnipeg.ca/ppms/>.
30
a3f5707d
JRT
31 If you'd like to try Perl::Critic without installing anything, there is
32 a web-service available at <http://perlcritic.com>. The web-service does
b9e35135
JRT
33 not yet support all the configuration features that are available in the
34 native Perl::Critic API, but it should give you a good idea of what it
7b2c2404
JRT
35 does. You can also invoke the perlcritic web-service from the
36 command-line by doing an HTTP-post, such as one of these:
a3f5707d 37
b4c7e33c
JRT
38 $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
39 $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
40 $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
a3f5707d
JRT
41
42 Please note that the perlcritic web-service is still alpha code. The URL
43 and interface to the service are subject to change.
b9e35135
JRT
44
45CONSTRUCTOR
a3f5707d
JRT
46 "new( [ -profile => $FILE, -severity => $N, -theme => $string, -include
47 => \@PATTERNS, -exclude => \@PATTERNS, -top => $N, -only => $B, -force
48 => $B, -verbose => $N ] )"
b4c7e33c 49 "new( -config => Perl::Critic::Config->new() )"
a3f5707d 50 "new()" Returns a reference to a new Perl::Critic object. Most arguments
b9e35135 51 are just passed directly into Perl::Critic::Config, but I have
a3f5707d
JRT
52 described them here as well. The default value for all arguments
53 can be defined in your .perlcriticrc file. See the
54 "CONFIGURATION" section for more information about that. All
55 arguments are optional key-value pairs as follows:
b9e35135
JRT
56
57 -profile is a path to a configuration file. If $FILE is not
58 defined, Perl::Critic::Config attempts to find a .perlcriticrc
59 configuration file in the current directory, and then in your
60 home directory. Alternatively, you can set the "PERLCRITIC"
61 environment variable to point to a file in another location. If
62 a configuration file can't be found, or if $FILE is an empty
63 string, then all Policies will be loaded with their default
64 configuration. See "CONFIGURATION" for more information.
65
66 -severity is the minimum severity level. Only Policy modules
7b2c2404 67 that have a severity greater than $N will be applied. Severity
b9e35135
JRT
68 values are integers ranging from 1 (least severe) to 5 (most
69 severe). The default is 5. For a given "-profile", decreasing
7b2c2404
JRT
70 the "-severity" will usually reveal more Policy violations. You
71 can set the default value for this option in your .perlcriticrc
72 file. Users can redefine the severity level for any Policy in
73 their .perlcriticrc file. See "CONFIGURATION" for more
74 information.
b9e35135 75
b4c7e33c
JRT
76 If it is difficult for you to remember whether severity "5" is
77 the most or least restrictive level, then you can use one of
78 these named values:
79
80 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
81 --------------------------------------------------------
82 -severity => 'gentle' -severity => 5
83 -severity => 'stern' -severity => 4
84 -severity => 'harsh' -severity => 3
85 -severity => 'cruel' -severity => 2
86 -severity => 'brutal' -severity => 1
87
7b2c2404
JRT
88 -theme is special expression that determines which Policies to
89 apply based on their respective themes. For example, the
90 following would load only Policies that have a 'bugs' AND 'pbp'
91 theme:
a3f5707d 92
7b2c2404 93 my $critic = Perl::Critic->new( -theme => 'bugs && pbp' );
a3f5707d 94
7b2c2404
JRT
95 Unless the "-severity" option is explicitly given, setting
96 "-theme" silently causes the "-severity" to be set to 1. You can
97 set the default value for this option in your .perlcriticrc
98 file. See the "POLICY THEMES" section for more information about
99 themes.
a3f5707d 100
b9e35135
JRT
101 -include is a reference to a list of string @PATTERNS. Policy
102 modules that match at least one "m/$PATTERN/imx" will always be
a3f5707d 103 loaded, irrespective of all other settings. For example:
b9e35135
JRT
104
105 my $critic = Perl::Critic->new(-include => ['layout'] -severity => 4);
106
7b2c2404 107 This would cause Perl::Critic to apply all the "CodeLayout::*"
b9e35135 108 Policy modules even though they have a severity level that is
7b2c2404
JRT
109 less than 4. You can set the default value for this option in
110 your .perlcriticrc file. You can also use "-include" in
111 conjunction with the "-exclude" option. Note that "-exclude"
112 takes precedence over "-include" when a Policy matches both
113 patterns.
b9e35135
JRT
114
115 -exclude is a reference to a list of string @PATTERNS. Policy
116 modules that match at least one "m/$PATTERN/imx" will not be
a3f5707d 117 loaded, irrespective of all other settings. For example:
b9e35135
JRT
118
119 my $critic = Perl::Critic->new(-exclude => ['strict'] -severity => 1);
120
7b2c2404
JRT
121 This would cause Perl::Critic to not apply the
122 "RequireUseStrict" and "ProhibitNoStrict" Policy modules even
123 though they have a severity level that is greater than 1. You
124 can set the default value for this option in your .perlcriticrc
125 file. You can also use "-exclude" in conjunction with the
126 "-include" option. Note that "-exclude" takes precedence over
127 "-include" when a Policy matches both patterns.
b9e35135 128
7b2c2404
JRT
129 -singlepolicy is a string "PATTERN". Only one policy that
130 matches "m/$PATTERN/imx" will be used. Policies that do not
131 match will be excluded. This option has precedence over the
ffe5f1a7 132 "-severity", "-theme", "-include", "-exclude", and "-only"
7b2c2404
JRT
133 options. You can set the default value for this option in your
134 .perlcriticrc file.
ffe5f1a7 135
b9e35135 136 -top is the maximum number of Violations to return when ranked
a3f5707d
JRT
137 by their severity levels. This must be a positive integer.
138 Violations are still returned in the order that they occur
139 within the file. Unless the "-severity" option is explicitly
140 given, setting "-top" silently causes the "-severity" to be set
7b2c2404
JRT
141 to 1. You can set the default value for this option in your
142 .perlcriticrc file.
a3f5707d
JRT
143
144 -only is a boolean value. If set to a true value, Perl::Critic
145 will only choose from Policies that are mentioned in the user's
146 profile. If set to a false value (which is the default), then
147 Perl::Critic chooses from all the Policies that it finds at your
7b2c2404
JRT
148 site. You can set the default value for this option in your
149 .perlcriticrc file.
b9e35135 150
b4c7e33c
JRT
151 -force is a boolean value that controls whether Perl::Critic
152 observes the magical "## no critic" pseudo-pragmas in your code.
153 If set to a true value, Perl::Critic will analyze all code. If
154 set to a false value (which is the default) Perl::Critic will
155 ignore code that is tagged with these comments. See "BENDING THE
7b2c2404
JRT
156 RULES" for more information. You can set the default value for
157 this option in your .perlcriticrc file.
b9e35135 158
b4c7e33c 159 -verbose can be a positive integer (from 1 to 11), or a literal
a3f5707d 160 format specification. See Perl::Critic::Violations for an
7b2c2404
JRT
161 explanation of format specifications. You can set the default
162 value for this option in your .perlcriticrc file.
a3f5707d 163
b9e35135
JRT
164 -config is a reference to a Perl::Critic::Config object. If you
165 have created your own Config object for some reason, you can
166 pass it in here instead of having Perl::Critic create one for
167 you. Using the "-config" option causes all the other options to
168 be silently ignored.
169
170METHODS
171 "critique( $source_code )"
172 Runs the $source_code through the Perl::Critic engine using all
173 the Policies that have been loaded into this engine. If
b4c7e33c
JRT
174 $source_code is a scalar reference, then it is treated as a
175 string of actual Perl code. If $source_code is a reference to an
b9e35135
JRT
176 instance of PPI::Document, then that instance is used directly.
177 Otherwise, it is treated as a path to a local file containing
b4c7e33c 178 Perl code. This method returns a list of Perl::Critic::Violation
b9e35135
JRT
179 objects for each violation of the loaded Policies. The list is
180 sorted in the order that the Violations appear in the code. If
181 there are no violations, this method returns an empty list.
182
a3f5707d 183 "add_policy( -policy => $policy_name, -params => \%param_hash )"
b9e35135 184 Creates a Policy object and loads it into this Critic. If the
a3f5707d
JRT
185 object cannot be instantiated, it will throw a fatal exception.
186 Otherwise, it returns a reference to this Critic.
b9e35135
JRT
187
188 -policy is the name of a Perl::Critic::Policy subclass module.
189 The 'Perl::Critic::Policy' portion of the name can be omitted
190 for brevity. This argument is required.
191
a3f5707d
JRT
192 -params is an optional reference to a hash of Policy parameters.
193 The contents of this hash reference will be passed into to the
194 constructor of the Policy module. See the documentation in the
195 relevant Policy module for a description of the arguments it
196 supports.
b9e35135 197
a3f5707d 198 " policies() "
b9e35135
JRT
199 Returns a list containing references to all the Policy objects
200 that have been loaded into this engine. Objects will be in the
201 order that they were loaded.
202
a3f5707d 203 " config() "
b9e35135
JRT
204 Returns the Perl::Critic::Config object that was created for or
205 given to this Critic.
206
207FUNCTIONAL INTERFACE
208 For those folks who prefer to have a functional interface, The
209 "critique" method can be exported on request and called as a static
210 function. If the first argument is a hashref, its contents are used to
211 construct a new Perl::Critic object internally. The keys of that hash
212 should be the same as those supported by the "Perl::Critic::new" method.
213 Here are some examples:
214
215 use Perl::Critic qw(critique);
216
217 # Use default parameters...
218 @violations = critique( $some_file );
219
220 # Use custom parameters...
221 @violations = critique( {-severity => 2}, $some_file );
222
223 # As a one-liner
224 %> perl -MPerl::Critic=critique -e 'print critique(shift)' some_file.pm
225
226 None of the other object-methods are currently supported as static
227 functions. Sorry.
228
229CONFIGURATION
a3f5707d
JRT
230 Most of the settings for Perl::Critic and each of the Policy modules can
231 be controlled by a configuration file. The default configuration file is
232 called .perlcriticrc. Perl::Critic will look for this file in the
233 current directory first, and then in your home directory. Alternatively,
234 you can set the "PERLCRITIC" environment variable to explicitly point to
235 a different file in another location. If none of these files exist, and
236 the "-profile" option is not given to the constructor, then all the
237 modules that are found in the Perl::Critic::Policy namespace will be
238 loaded with their default configuration.
239
240 The format of the configuration file is a series of INI-style blocks
b9e35135
JRT
241 that contain key-value pairs separated by '='. Comments should start
242 with '#' and can be placed on a separate line or after the name-value
a3f5707d
JRT
243 pairs if you desire.
244
245 Default settings for Perl::Critic itself can be set before the first
246 named block. For example, putting any or all of these at the top of your
247 configuration file will set the default value for the corresponding
7b2c2404 248 constructor argument.
a3f5707d 249
b4c7e33c 250 severity = 3 #Integer or named level
a3f5707d
JRT
251 only = 1 #Zero or One
252 force = 0 #Zero or One
253 verbose = 4 #Integer or format spec
254 top = 50 #A positive integer
7b2c2404 255 theme = (pbp || security) && bugs #A theme expression
a3f5707d
JRT
256 include = NamingConventions ClassHierarchies #Space-delimited list
257 exclude = Variables Modules::RequirePackage #Space-delimited list
258
259 The remainder of the configuration file is a series of blocks like this:
260
261 [Perl::Critic::Policy::Category::PolicyName]
262 severity = 1
ffe5f1a7
JRT
263 set_themes = foo bar
264 add_themes = baz
a3f5707d
JRT
265 arg1 = value1
266 arg2 = value2
b9e35135
JRT
267
268 "Perl::Critic::Policy::Category::PolicyName" is the full name of a
269 module that implements the policy. The Policy modules distributed with
270 Perl::Critic have been grouped into categories according to the table of
271 contents in Damian Conway's book Perl Best Practices. For brevity, you
272 can omit the 'Perl::Critic::Policy' part of the module name.
273
274 "severity" is the level of importance you wish to assign to the Policy.
275 All Policy modules are defined with a default severity value ranging
276 from 1 (least severe) to 5 (most severe). However, you may disagree with
277 the default severity and choose to give it a higher or lower severity,
b4c7e33c
JRT
278 based on your own coding philosophy. You can set the "severity" to an
279 integer from 1 to 5, or use one of the equivalent names:
280
281 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
282 ----------------------------------------------------
283 gentle 5
284 stern 4
285 harsh 3
286 cruel 2
287 brutal 1
288
289 "set_themes" sets the theme for the Policy and overrides its default
290 theme. The argument is a string of one or more whitespace-delimited
291 alphanumeric words. Themes are case-insensitive. See "POLICY THEMES" for
292 more information.
293
294 "add_themes" appends to the default themes for this Policy. The argument
295 is a string of one or more whitespace-delimited words. Themes are
296 case-insensitive. See "POLICY THEMES" for more information.
b9e35135
JRT
297
298 The remaining key-value pairs are configuration parameters that will be
299 passed into the constructor for that Policy. The constructors for most
300 Policy objects do not support arguments, and those that do should have
301 reasonable defaults. See the documentation on the appropriate Policy
302 module for more details.
303
304 Instead of redefining the severity for a given Policy, you can
305 completely disable a Policy by prepending a '-' to the name of the
306 module in your configuration file. In this manner, the Policy will never
307 be loaded, regardless of the "-severity" given to the Perl::Critic
308 constructor.
309
310 A simple configuration might look like this:
311
a3f5707d
JRT
312 #--------------------------------------------------------------
313 # I think these are really important, so always load them
314
315 [TestingAndDebugging::RequireUseStrict]
316 severity = 5
317
318 [TestingAndDebugging::RequireUseWarnings]
319 severity = 5
b9e35135 320
a3f5707d
JRT
321 #--------------------------------------------------------------
322 # I think these are less important, so only load when asked
b9e35135 323
a3f5707d
JRT
324 [Variables::ProhibitPackageVars]
325 severity = 2
b9e35135 326
a3f5707d 327 [ControlStructures::ProhibitPostfixControls]
b4c7e33c
JRT
328 allow = if unless # My custom configuration
329 severity = cruel # Same as "severity = 2"
b9e35135 330
a3f5707d
JRT
331 #--------------------------------------------------------------
332 # Give these policies a custom theme. I can activate just
333 # these policies by saying `perlcritic -theme larry`
b9e35135 334
a3f5707d 335 [Modules::RequireFilenameMatchesPackage]
ffe5f1a7 336 add_themes = larry
b9e35135 337
a3f5707d 338 [TestingAndDebugging::RequireTestLables]
ffe5f1a7 339 add_themes = larry curly moe
b9e35135 340
a3f5707d
JRT
341 #--------------------------------------------------------------
342 # I do not agree with these at all, so never load them
b9e35135 343
a3f5707d
JRT
344 [-NamingConventions::ProhibitMixedCaseVars]
345 [-NamingConventions::ProhibitMixedCaseSubs]
b9e35135 346
a3f5707d
JRT
347 #--------------------------------------------------------------
348 # For all other Policies, I accept the default severity,
349 # so no additional configuration is required for them.
b9e35135 350
ffe5f1a7 351 For additional configuration examples, see the perlcriticrc file that is
7b2c2404 352 included in this examples directory of this distribution.
ffe5f1a7 353
e1fb2898 354 Damian Conway's own Perl::Critic configuration is also included in this
34883f65 355 distribution as examples/perlcriticrc-conway.
e1fb2898 356
b9e35135
JRT
357THE POLICIES
358 A large number of Policy modules are distributed with Perl::Critic. They
359 are described briefly in the companion document
360 Perl::Critic::PolicySummary and in more detail in the individual modules
b4c7e33c
JRT
361 themselves. Say ""perlcritic -doc PATTERN"" to see the perldoc for all
362 Policy modules that match the regex "m/PATTERN/imx"
b9e35135 363
a3f5707d
JRT
364POLICY THEMES
365 Each Policy is defined with one or more "themes". Themes can be used to
366 create arbitrary groups of Policies. They are intended to provide an
b4c7e33c
JRT
367 alternative mechanism for selecting your preferred set of Policies. For
368 example, you may wish disable a certain subset of Policies when
369 analyzing test scripts. Conversely, you may wish to enable only a
370 specific subset of Policies when analyzing modules.
371
372 The Policies that ship with Perl::Critic are have been broken into the
373 following themes. This is just our attempt to provide some basic logical
374 groupings. You are free to invent new themes that suit your needs.
375
376 THEME DESCRIPTION
377 --------------------------------------------------------------------------
378 core All policies that ship with Perl::Critic
379 pbp Policies that come directly from "Perl Best Practices"
380 bugs Policies that that prevent or reveal bugs
381 maintenance Policies that affect the long-term health of the code
382 cosmetic Policies that only have a superficial effect
383 complexity Policies that specificaly relate to code complexity
384 security Policies that relate to security issues
385 tests Policies that are specific to test scripts
386
387 Any Policy may fit into multiple themes. Say "perlcritic -list" to get a
388 listing of all available Policies and the themes that are associated
389 with each one. You can also change the theme for any Policy in your
390 .perlcriticrc file. See the "CONFIGURATION" section for more information
391 about that.
392
7b2c2404
JRT
393 Using the "-theme" option, you can create an arbitrarily complex rule
394 that determines which Policies will be loaded. Precedence is the same as
395 regular Perl code, and you can use parens to enforce precedence as well.
396 Supported operators are:
a3f5707d 397
7b2c2404 398 Operator Altertative Example
a3f5707d 399 ----------------------------------------------------------------------------
7b2c2404
JRT
400 && and 'pbp && core'
401 || or 'pbp || (bugs && security)'
402 ! not 'pbp && ! (portability || complexity)'
a3f5707d 403
7b2c2404
JRT
404 Theme names are case-insensitive. If the "-theme" is set to an empty
405 string, then it evaluates as true all Policies.
a3f5707d 406
b9e35135
JRT
407BENDING THE RULES
408 Perl::Critic takes a hard-line approach to your code: either you comply
409 or you don't. In the real world, it is not always practical (nor even
410 possible) to fully comply with coding standards. In such cases, it is
411 wise to show that you are knowingly violating the standards and that you
412 have a Damn Good Reason (DGR) for doing so.
413
414 To help with those situations, you can direct Perl::Critic to ignore
415 certain lines or blocks of code by using pseudo-pragmas:
416
417 require 'LegacyLibaray1.pl'; ## no critic
418 require 'LegacyLibrary2.pl'; ## no critic
419
420 for my $element (@list) {
421
422 ## no critic
423
424 $foo = ""; #Violates 'ProhibitEmptyQuotes'
425 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
426 #Some more evil code...
427
428 ## use critic
429
430 #Some good code...
431 do_something($_);
432 }
433
434 The "## no critic" comments direct Perl::Critic to ignore the remaining
7b2c2404
JRT
435 lines of code until the end of the current block, or until a ""## use
436 critic"" comment is found (whichever comes first). If the "## no critic"
b9e35135
JRT
437 comment is on the same line as a code statement, then only that line of
438 code is overlooked. To direct perlcritic to ignore the "## no critic"
439 comments, use the "-force" option.
440
441 A bare "## no critic" comment disables all the active Policies. If you
442 wish to disable only specific Policies, add a list of Policy names as
7b2c2404 443 arguments, just as you would for the "no strict" or "no warnings"
b9e35135
JRT
444 pragmas. For example, this would disable the "ProhibitEmptyQuotes" and
445 "ProhibitPostfixControls" policies until the end of the block or until
446 the next "## use critic" comment (whichever comes first):
447
448 ## no critic (EmptyQuotes, PostfixControls)
449
b4c7e33c
JRT
450 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
451 $foo = "";
452
453 # Now exempt ControlStructures::ProhibitPostfixControls
454 $barf = bar() if $foo;
b9e35135 455
b4c7e33c
JRT
456 # Still subjected to ValuesAndExpression::RequireNumberSeparators
457 $long_int = 10000000000;
458
459 Since the Policy names are matched against the "## no critic" arguments
460 as regular expressions, you can abbreviate the Policy names or disable
461 an entire family of Policies in one shot like this:
b9e35135
JRT
462
463 ## no critic (NamingConventions)
464
b4c7e33c
JRT
465 # Now exempt from NamingConventions::ProhibitMixedCaseVars
466 my $camelHumpVar = 'foo';
467
468 # Now exempt from NamingConventions::ProhibitMixedCaseSubs
469 sub camelHumpSub {}
b9e35135
JRT
470
471 The argument list must be enclosed in parens and must contain one or
7b2c2404
JRT
472 more comma-separated barewords (e.g. don't use quotes). The "## no
473 critic" pragmas can be nested, and Policies named by an inner pragma
b9e35135
JRT
474 will be disabled along with those already disabled an outer pragma.
475
7b2c2404
JRT
476 Some Policies like "Subroutines::ProhibitExcessComplexity" apply to an
477 entire block of code. In those cases, "## no critic" must appear on the
478 line where the violation is reported. For example:
479
480 sub complicated_function { ## no critic (ProhibitExcessComplexity)
481 # Your code here...
482 }
483
484 Policies such as "Documentation::RequirePodSections" apply to the entire
485 document, in which case violations are reported at line 1. But if the
486 file requires a shebang line, it is impossible to put "## no critic" on
487 the first line of the file. This is a known limitation and it will be
488 addressed in a future release. As a workaround, you can disable the
489 affected policies at the command-line or in your .perlcriticrc file. But
490 beware that this will affect the analysis of all files.
491
b9e35135
JRT
492 Use this feature wisely. "## no critic" should be used in the smallest
493 possible scope, or only on individual lines of code. And you should
494 always be as specific as possible about which policies you want to
495 disable (i.e. never use a bare "## no critic"). If Perl::Critic
496 complains about your code, try and find a compliant solution before
497 resorting to this feature.
498
499IMPORTANT CHANGES
500 Perl-Critic is evolving rapidly, so some of the interfaces have changed
501 in ways that are not backward-compatible. If you have been using an
502 older version of Perl-Critic and/or you have been developing custom
503 Policy modules, please read this section carefully.
504
7b2c2404
JRT
505 VERSION 0.23
506 In version 0.23, the syntax for theme rules changed. The mathematical
507 operators ( "*", "+", "-" ) are no longer supported. You must use
508 logical operators instead ( "&&", "!", "||" ). However the meanings of
509 these operators is effectively the same. See "POLICY THEMES" for more
510 details.
511
a3f5707d
JRT
512 VERSION 0.21
513 In version 0.21, we introduced the concept of policy "themes". All you
514 existing custom Policies should still be compatible. But to take
515 advantage of the theme feature, you should add a "default_themes" method
516 to your custom Policy modules. See Perl::Critic::DEVELOPER for an
517 up-to-date guide on creating Policy modules.
518
519 The internals of Perl::Critic were also refactored significantly. The
520 public API is largely unchanged, but if you've been accessing bits
521 inside Perl::Critic, then you may be in for a surprise.
522
b9e35135
JRT
523 VERSION 0.16
524 Starting in version 0.16, you can add a list Policy names as arguments
525 to the "## no critic" pseudo-pragma. This feature allows you to disable
526 specific policies. So if you have been in the habit of adding additional
527 words after "no critic", then those words might cause unexpected
7b2c2404 528 results. If you want to append other stuff to the "## no critic"
b9e35135
JRT
529 comment, then terminate the pseudo-pragma with a semi-colon, and then
530 start another comment. For example:
531
a3f5707d
JRT
532 #This may not work as expected.
533 $email = 'foo@bar.com'; ## no critic for literal '@'
b9e35135 534
a3f5707d
JRT
535 #This will work.
536 $email = 'foo@bar.com'; ## no critic; #for literal '@'
b9e35135 537
a3f5707d
JRT
538 #This is even better.
539 $email = 'foo@bar.com'; ## no critic (RequireInterpolation);
b9e35135
JRT
540
541 VERSION 0.14
542 Starting in version 0.14, the interface to Perl::Critic::Violation
543 changed. This will also break any custom Policy modules that you might
544 have written for earlier modules. See Perl::Critic::DEVELOPER for an
545 up-to-date guide on creating Policy modules.
546
547 The notion of "priority" was also replaced with "severity" in version
548 0.14. Consequently, the default behavior of Perl::Critic is to only load
549 the most "severe" Policy modules, rather than loading all of them. This
550 decision was based on user-feedback suggesting that Perl-Critic should
551 be less critical for new users, and should steer them toward gradually
552 increasing the strictness as they progressively adopt better coding
553 practices.
554
555 VERSION 0.11
556 Starting in version 0.11, the internal mechanics of Perl-Critic were
557 rewritten so that only one traversal of the PPI document tree is
558 required. Unfortunately, this will break any custom Policy modules that
559 you might have written for earlier versions. Converting your policies to
560 work with the new version is pretty easy and actually results in cleaner
561 code. See Perl::Critic::DEVELOPER for an up-to-date guide on creating
562 Policy modules.
563
564THE Perl::Critic PHILOSOPHY
565 Coding standards are deeply personal and highly subjective. The
566 goal of Perl::Critic is to help you write code that conforms with a
567 set of best practices. Our primary goal is not to dictate what
568 those practices are, but rather, to implement the practices
569 discovered by others. Ultimately, you make the rules --
570 Perl::Critic is merely a tool for encouraging consistency. If there
571 is a policy that you think is important or that we have overlooked,
572 we would be very grateful for contributions, or you can simply load
573 your own private set of policies into Perl::Critic.
574
575EXTENDING THE CRITIC
576 The modular design of Perl::Critic is intended to facilitate the
577 addition of new Policies. You'll need to have some understanding of PPI,
578 but most Policy modules are pretty straightforward and only require
579 about 20 lines of code. Please see the Perl::Critic::DEVELOPER file
580 included in this distribution for a step-by-step demonstration of how to
581 create new Policy modules.
582
583 If you develop any new Policy modules, feel free to send them to
759f1e90
JRT
584 "<thaljef@cpan.org>" and I'll be happy to put them into the Perl::Critic
585 distribution. Or if you would like to work on the Perl::Critic project
b9e35135
JRT
586 directly, check out our repository at <http://perlcritic.tigris.org>. To
587 subscribe to our mailing list, send a message to
759f1e90
JRT
588 "<dev-subscribe@perlcritic.tigris.org>".
589
590 The Perl::Critic team is also available for hire. If your organization
591 has its own coding standards, we can create custom Policies to enforce
592 your local guidelines. Or if your code base is prone to a particular
593 defect pattern, we can design Policies that will help you catch those
594 costly defects before they go into production. To discuss your needs
595 with the Perl::Critic team, just contact "<thaljef@cpan.org>".
b9e35135
JRT
596
597PREREQUISITES
598 Perl::Critic requires the following modules:
599
7b2c2404
JRT
600 B::Keywords
601
b9e35135
JRT
602 Config::Tiny
603
604 File::Spec
605
606 IO::String
607
608 List::Util
609
610 List::MoreUtils
611
612 Module::Pluggable
613
614 PPI
615
616 Pod::Usage
617
618 Pod::PlainText
619
b9e35135
JRT
620 String::Format
621
622 The following modules are optional, but recommended for complete
623 testing:
624
625 Test::Pod
626
627 Test::Pod::Coverage
628
629BUGS
630 Scrutinizing Perl code is hard for humans, let alone machines. If you
631 find any bugs, particularly false-positives or false-negatives from a
632 Perl::Critic::Policy, please submit them to
633 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
634
635CREDITS
636 Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
637
638 Damian Conway - For writing Perl Best Practices, finally :)
639
640 Chris Dolan - For contributing the best features and Policy modules.
641
b4c7e33c 642 Andy Lester - Wise sage and master of all-things-testing.
b9e35135 643
b4c7e33c 644 Elliot Shank - The self-proclaimed quality freak.
ffe5f1a7 645
b4c7e33c 646 Giuseppe Maxia - For all the great ideas and positive encouragement.
ffe5f1a7 647
b9e35135
JRT
648 and Sharon, my wife - For putting up with my all-night code sessions.
649
650AUTHOR
651 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
652
653COPYRIGHT
7b2c2404 654 Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. All rights reserved.
b9e35135
JRT
655
656 This program is free software; you can redistribute it and/or modify it
657 under the same terms as Perl itself. The full text of this license can
658 be found in the LICENSE file included with this module.
659