Perl Critic In Depth

Jeffrey Thalhammer

S o f t w a r e S y s t e m s

jeff@imaginative-software.com

Thursday, September 30, 2010

Some Ways Are Better Than Others
San Francisco Perl Mongers
July 27, 2010


HaveYou Ever?...


print ‘Hello, my name is $namen’;


eval ‘reqire Some::Module’;


if(not $foo && $bar or $baz){
...
}


if($this == ‘that’){
...
}


What Is Perl::Critic?



• Static Source Code Analyzer



• Like “lint” but for Perl code



• Finds bugs & enforces style



• Finds bugs & enforces style
• Mostly based on Perl Best Practices


Genesis


Genesis

• Large legacy code base (~500k lines)


Genesis

• Evolved organically over 10 years


Genesis

• Many developers with various skill levels


Genesis

• “Worst code I’ve ever seen.”


Genesis

• “Worst code I’ve ever seen.”
• “Most proﬁtable code I’ve ever seen.”


Genesis

• Highly inconsistent (anti-patterns)


Genesis

• Extremely complicated code


Genesis

• Much copy & pasted code


Genesis

• Much copy & pasted code
• Cargo cult


Behold!


But How Can I Get
Others To Learn Perl
Best Practices?


Introducing PPI


Introducing PPI

• By Adam Kennedy (a.k.a. alias)


Introducing PPI

• “Parse Perl Independently”


Introducing PPI

• Parse and lex Perl code into DOM


Introducing PPI

• Only perl can parse Perl


Introducing PPI

• Only perl can parse Perl
• PPI comes pretty darn close


And Perl::Critic Was
Born


Getting Feet Wet
File: Bar.pm

1 package Foo;
2
3 sub showGreeting ($) {
4 my $name = shift;
5 return undef if not $name;
6 open FH, “>out.txt”;
7 print FH ‘Hello $namen’;
8 }


Getting Feet Wet
USAGE: perlcritic FILENAME

[jeff@callahan:/Users/jeff]$ perlcritic Bar.pm
Package declaration must match filename at line 1, column 1. Correct
the filename or package statement. (Severity: 5)
Subroutine prototypes used at line 3, column 1. See page 194 of PBP.
(Severity: 5)
Code before strictures are enabled at line 3, column 1. See page 429
of PBP. (Severity: 5)
"return" statement with explicit "undef" at line 5, column 3. See
page 199 of PBP. (Severity: 5)
Bareword file handle opened at line 6, column 3. See pages 202,204
of PBP. (Severity: 5)
Two-argument "open" used at line 6, column 3. See page 207 of PBP.
(Severity: 5)


A Closer Look

Two-argument "open" used at line 6, column 3.
See page 207 of PBP. (Severity: 5)


A Closer Look
Description



A Closer Look
Description Location



A Closer Look


PBP
Reference


A Closer Look


PBP
Severity
Reference


Fixing Violations
File: Bar.pm

1 package Bar;
2
3 use strict;
4 use warnings;
5
6 sub showGreeting {
7 my $name = shift;
8 return if not $name;
9 open my $fh, ‘>’, “out.txt”;
10 print $fh ‘Hello $name’;
11 }

Try Again

Bar.pm source OK


Tightening The Screws
USAGE: perlcritic --serverity N FILENAME

[jeff@callahan:/Users/jeff]$ perlcritic --severity 4 Bar.pm
Module does not end with "1;" at line 6, column 1. Must end with a
recognizable true value. (Severity: 4)
Subroutine "showGreeting" does not end with "return" at line 6,
column 1. See page 197 of PBP. (Severity: 4)
Close filehandles as soon as possible after opening them at line 9,
column 1. See page 209 of PBP. (Severity: 4)


File: Bar.pm

1 package Bar;
2
3 use strict;
4 use warnings;
5
6 sub showGreeting {
7 my $name = shift;
8 return if not $name;
9 open my $fh, ‘>’, $name;
10 print $fh ‘Hello $name’;
11 close $fh;
12 return 1;
13 }
14
15 1;

One More Time

Bar.pm source OK


RCS keywords $Revision$, $HeadURL$, $Date$ not found at line 1, column 1. See page 441 of
PBP. (Severity: 2)
No "$VERSION" variable found at line 1, column 1. See page 404 of PBP. (Severity: 2)
Return value of "close" ignored at line 11, column 1. Check the return value of "close" for
success. (Severity: 2)


PBP. (Severity: 2)

RCS keywords $Id$ not found at line 1, column 1. See page 441 of PBP. (Severity: 2)
PBP. (Severity: 2)
RCS keywords $Revision$, $Source$, $Date$ not found at line 1, column 1. See page 441 of
PBP. (Severity: 2)
Subroutine "showGreeting" is not all lower case or all upper case at line 6, column 1. See
pages 45,46 of PBP. (Severity: 1)
Return value of "open" ignored at line 9, column 1. Check the return value of "open" for
Return value of flagged function ignored - open at line 9, column 1. See pages 208,278 of
PBP. (Severity: 1)
File handle for "print" or "printf" is not braced at line 10, column 1. See page 217 of
PBP. (Severity: 1)
Return value of flagged function ignored - print at line 10, column 1. See pages 208,278 of
PBP. (Severity: 1)
String *may* require interpolation at line 10, column 11. See page 51 of PBP. (Severity:
1)

Five Levels Of Severity


• 5 (Highest): Likely bug or widely accepted practice


• 1 (Lowest): Purely cosmetic or highly controversial



• Severities are determined by Policy authors



• Also have names (brutal, cruel, harsh, stern, gentle)



• Also have names (brutal, cruel, harsh, stern, gentle)
• Can be conﬁgured

Configuration
perlcritic [-12345 | --brutal | --cruel | --harsh | --stern | --gentle]
[--severity number | name] [{-p | --profile} file | --noprofile]
[--top [ number ]] [--theme expression] [--include pattern]
[--exclude pattern] [{-s | --single-policy} pattern]
[--only | --noonly] [--profile-strictness {warn|fatal|quiet}]
[--force | --noforce] [--statistics] [--statistics-only]
[--count | -C] [--verbose {number | format}]
[--color | --nocolor] [--pager pager] [--quiet]
[--color-severity-highest color_specification]
[--color-severity-high color_specification]
[--color-severity-medium color_specification]
[--color-severity-low color_specification]
[--color-severity-lowest color_specification]
[--files-with-violations | -l]
[--files-without-violations | -L]
{FILE | DIRECTORY | STDIN}

perlcritic --profile-proto

perlcritic { --list | --list-enabled | --list-themes | --doc pattern [...] }

perlcritic { --help | --options | --man | --version }


Conﬁguration


Conﬁguration

• .perlcriticrc ﬁle


Conﬁguration

• In home directory or project directory


Conﬁguration

• In home directory or project directory
• INI-style syntax


Conﬁguration
File: ~/.perlcriticrc

# Global options here
severity = 2
pager = /usr/bin/less
color = 1

These will be the
defaults, unless
overridden at the
command-line

PBP. (Severity: 2)

Default severity is now 2, as
deﬁned in .perlcriticrc ﬁle


Getting More
Information
USAGE: perlcritic --verbose 8 FILENAME

[jeff@callahan:/Users/jeff]$ perlcritic --verbose 8 Bar.pm
[Miscellanea::RequireRcsKeywords] RCS keywords $Revision$, $Source$, $Date$ not found at
line 1, column 1. (Severity: 2)
[Modules::RequireVersionVar] No "$VERSION" variable found at line 1, column 1. (Severity:
2)
[InputOutput::RequireCheckedClose] Return value of "close" ignored at line 11, column 1.
(Severity: 2)

Now showing name of the Policy


Conﬁguration
File: ~/.perlcriticrc
# Global options here
severity = 2
verbose = 8

# Policy options here
[Modules::RequireVersionVar]
severity = 1

# These policies are disabled
[-Miscellanea::RequireRcsKeywords]
[-InputOutput::RequireCheckedClose]


Now running with
severity = 2, and
verbose = 8

Bar.pm source OK


Eleven Levels Of
Verbosity


Eleven Levels Of
Verbosity
• Increasing levels of detail


Eleven Levels Of
Verbosity
• Can be customized with printf-style formats:
“%m near %s at line %l in file %f”


Eleven Levels Of
Verbosity

• Some of the available details:


Eleven Levels Of
Verbosity

• Message, diagnostic (PBP pages), POD extract


Eleven Levels Of
Verbosity

• Line, column, ﬁle name, ﬁle path, severity


Eleven Levels Of
Verbosity

• Source code, PPI element, policy name

Eleven Levels Of
Verbosity

• Source code, PPI element, policy name
• Integrates with editor’s compile-mode (vim, emacs)

Lots of Policies


Lots of Policies

• 128 Policies in Perl::Critic core


Lots of Policies

• 85 Policies taken directly from PBP


Lots of Policies

• Dozens of add-on Policies in CPAN


Lots of Policies

• Dozens of add-on Policies in CPAN
• Covering all aspects of programming


Just A Taste


Just A Taste
• BuiltinFunctions::ProhibitVoidMap


Just A Taste
• ControlStructures::ProhibitUnreachableCode


Just A Taste
• NamingConventions::ProhibitAmbiguousNames


Just A Taste
• Subroutines::ProhibitExcessComplexity


Just A Taste
• CodeLayout::RequireTidyCode


Just A Taste
• RegularExpressions::ProhibitFixedStringMatches


Just A Taste
• RegularExpressions::ProhibitFixedStringMatches
• Documentation::RequirePodSections

Tips For Choosing Policies


• Use --profile-proto option to generate your
first .perlcriticrc file.


• Start with --severity 5 and work your way
down.


down.
• Use the --doc option to view Policy
documentation.


down.
documentation.
• Disable or reconﬁgure Policies that you don’t
agree with.


down.
documentation.
• Disable or reconﬁgure Policies that you don’t
agree with.
• Don’t try to do it all at once.

Bending The Rules
#!/usr/bin/perl

print “Hin” if $^O eq ‘darwin’;
print “Hellon” if $^O =~ /win/i;


Bending The Rules
#!/usr/bin/perl


• This would violate ProhibitPostﬁxControls


Bending The Rules
#!/usr/bin/perl


• This would violate ProhibitPostﬁxControls
• But we really like the way it reads


Bending The Rules
#!/usr/bin/perl

## no critic


## use critic

• ## no critic disables Perl::Critic until end
of block or until ## use critic

Bending The Rules

#!/usr/bin/perl

frobulate($this) if $that; ## no critic

• When attached to a line of code ## no
critic disables Perl::Critic for that line only


Bending The Rules

#!/usr/bin/perl

frobulate($this) if $that; ## no critic (ProhibitPostfixControls)

You can also specify exactly
which Policies to disable


Perl::Critic Applied
As command-line tool...
$> perlcritic --verbose 8 MyModule.pm

As pragma...
#!/usr/bin/perl

use strict;
use warnings;
use criticism ‘brutal’;
...


Perl::Critic Applied

As test library...
#!/usr/bin/perl

use Test::Perl::Critic;
all_critic_ok();


Tips For Working With
Legacy Code


Legacy Code
• Use --statistics option to identify hotspots.


Legacy Code
• Segregate new code from old code.


Legacy Code
• Use “no critic” annotations around blocks of
nasty legacy code.


Legacy Code
nasty legacy code.
• Don’t mix clean-up commits with regular work.


Legacy Code
nasty legacy code.
• Don’t mix clean-up commits with regular work.
• Use Test::Perl::Critic::Progressive to chip away at
the problem.


Test::Perl::Critic::Progressive



• TAP-compatible test module.



• Always passes the ﬁrst time.



• Makes a record of violations (in a local ﬁle).



• Subsequent runs will fail if new violations are
added.



• Subsequent runs will fail if new violations are
added.
• Works best as part of continuous integration
system.


Extending Perl::Critic


• Each Policy is a module in the Perl::Critic::Policy
namespace.


namespace.
• Each Policy extends the Perl::Critic::Policy
abstract base class.


namespace.
• Automatically loaded via Module::Pluggable.


namespace.
• Sometimes as little as 20 lines of code.


namespace.
• Sometimes as little as 20 lines of code.
• See POD for step-by-step tutorial.


• Policies do not have to be from PBP.



• Your Policies can conﬂict with existing ones.



• Your Policies can conﬂict with existing ones.
• Policies can be general or domain-speciﬁc.


Suppose We Want To
Ban Really Complex
Boolean Expressions...
if ($foo && ($bar || $baz) || !($bar && $baz) || $qux) {
...
}


package Perl::Critic::Policy::ValuesAndExpressions::ProhibitComplexBoolean;

use strict;
use warnings;
use Readonly;

use Perl::Critic::Utils ‘:severities’;
use base ‘Perl::Critic::Policy’;

sub default_severity{ return $SEVERITY_HIGH }
sub default_theme{ return qw(complexity) }
sub supported_params{ return () }



Put Policy in
use strict;
Perl::Critic::Policy namespace
use warnings;
use Readonly;





Policies organized by
use strict;
PBP table of contents
use warnings;
use Readonly;





use strict;
use warnings; Some boilerplate
use Readonly;





use strict;
use warnings;
use Readonly; Extend the Policy baseclass





use strict;
use warnings;
use Readonly;

Deﬁne default attributes


sub default_severity{ return $SEVERITY_HIGH };
sub default_theme{ return qw(complexity) };

Readonly::Scalar my $DESC =>
'Too many boolean operators';
Readonly::Scalar my $EXPL =>
'Complex expressions are hard to read';


Just declaring some variables to
store the Description and
Explanation

sub default_severity{ return $SEVERITY_HIGH };
sub default_theme{ return qw(complexity) };

Readonly::Scalar my $DESC =>
'Too many boolean operators';
Readonly::Scalar my $EXPL =>
'Complex expressions are hard to read';


How Does PPI See Your Code?
USAGE: ppidump ‘some source code’
USAGE: ppidump STDIN

$> ./tools/ppidump 'if($foo && $bar && $baz){}'
PPI::Document
PPI::Statement::Compound
PPI::Token::Word 'if'
PPI::Structure::Condition ... )
(
PPI::Statement::Expression
PPI::Token::Symbol '$foo'
PPI::Token::Operator '&&'
PPI::Token::Symbol '$bar'
PPI::Token::Symbol '$baz'
PPI::Structure::Block { ... }


PPI::Document
PPI::Token::Word 'if' This is where we
(
want to look for
PPI::Token::Symbol '$foo' violations


PPI::Document
PPI::Token::Word 'if'
(
PPI::Token::Symbol '$foo' The offensive code
PPI::Token::Operator '&&' is in a child node

sub applies_to { return ‘PPI::Structure::Condition’ }

sub violates {
my ( $self, $elem, $doc ) = @_;
# meat goes here!
}


Declare which types of PPI
elements we are interested in

sub violates {
# meat goes here!
}



sub violates {
# meat goes here!
} As document is traversed, we
get called each time a
PPI::Structure::Conditional is
encountered



sub violates {
# meat goes here!
We also get a reference to
}
the entire document



sub violates {
# meat goes here!
}

Your job is to ﬁgure out if this
$elem is violating the Policy


sub violates {
my $ops = $elem->find(‘PPI::Token::Operator’);
my $count = grep { _is_boolean($_) } @{$ops}
if ($count > 3) {
return $self->violation($DESC, $EXPL, $elem )
}
}

sub _is_boolean {
my ($elem) = @_;
return $elem->content()
=~ m/^ and | or | not | && | || $/x;
}

sub violates {
if ($count > 3) {
}
} Search recursively for all
Operators
sub _is_boolean {
my ($elem) = @_;
=~ m/^ and | or | not | && | || $/x;
}

sub violates {
if ($count > 3) {
}
} Count those that are
boolean
sub _is_boolean {
my ($elem) = @_;
=~ m/^ and | or | not | && | || $/x;
}

sub violates {
if ($count > 3) {
}
}
Using regex to determine
sub _is_boolean { type of operator
my ($elem) = @_;
=~ m/^ and | or | not | && | || $/x;
}

sub violates {
if ($count > 3) {
}
} Return a violation if count
exceeds maximum
sub _is_boolean {
my ($elem) = @_;
=~ m/^ and | or | not | && | || $/x;
}

Testing Your Policy


Testing Your Policy

• Use Test::Perl::Critic::Policy.


Testing Your Policy

• Specify test cases using POD-like notation.


Testing Your Policy

• Specify test cases using POD-like notation.
• Write Perl as Perl, not strings.


File: t/ValuesAndExpressions/ProhbitComplexBoolean.run
#----------------------------------------
## name Within limits
## failures 0
## cut

if ($foo && $bar) {}
while ($foo or $bar || $baz) {}

#----------------------------------------
## name Too many operators
## failures 2
## cut

if ($foo && $bar or not $baz and $quxx) {}
while ($foo or $bar || $baz && quxx and not $quip) {}


#----------------------------------------
## name Within limits Give test a name
## failures 0
## cut


#----------------------------------------
## failures 2
## cut



#----------------------------------------
## failures 0 How many violations to expect
## cut


#----------------------------------------
## failures 2
## cut



#----------------------------------------
## failures 0
## cut
Write offending code

#----------------------------------------
## failures 2
## cut



#----------------------------------------
## failures 0
## cut


#----------------------------------------
Code region ends when
## failures 2 next “## name” is found
## cut



Questions?


Thank You!


Perl Critic In Depth

Recommended

Recommended

More Related Content

Similar to Perl Critic In Depth

Similar to Perl Critic In Depth (10)

More from Jeffrey Ryan Thalhammer

More from Jeffrey Ryan Thalhammer (6)

Perl Critic In Depth