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

San Francisco Perl MongersJuly 27, 2010

Some Ways Are Better Than Others

HaveYou Ever?...

print ‘Hello, my name is $name\n’;

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

• Mostly based on Perl Best Practices

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 profitable 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

• 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

package Foo;

sub showGreeting ($) {my $name = shift;return undef if not $name;open FH, “>out.txt”;print FH ‘Hello $name\n’;

File: Bar.pm

12345678

Getting Feet Wet

[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)

USAGE: perlcritic FILENAME

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 Reference Severity

A Closer Look

package Bar;

use strict;use warnings;

sub showGreeting {my $name = shift;return if not $name;open my $fh, ‘>’, “out.txt”;print $fh ‘Hello $name’;

File: Bar.pm

1234567891011

Fixing Violations

[jeff@callahan:/Users/jeff]$ perlcritic Bar.pm Bar.pm source OK

USAGE: perlcritic FILENAME

Try Again

[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)

USAGE: perlcritic --serverity N FILENAME

Tightening The Screws

package Bar;

use strict;use warnings;

sub showGreeting {my $name = shift;return if not $name;open my $fh, ‘>’, $name;print $fh ‘Hello $name’;close $fh;return 1;}

123456789101112131415

File: Bar.pm

One More Time

[jeff@callahan:/Users/jeff]$ perlcritic --severity 4 Bar.pm Bar.pm source OK

USAGE: perlcritic --serverity N FILENAME[jeff@callahan:/Users/jeff]$ perlcritic --severity 2 Bar.pm 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)

[jeff@callahan:/Users/jeff]$ perlcritic --severity 1 Bar.pm RCS keywords $Id$ not found at line 1, column 1. See page 441 of PBP. (Severity: 2)RCS keywords $Revision$, $HeadURL$, $Date$ not found at line 1, column 1. See page 441 of PBP. (Severity: 2)RCS keywords $Revision$, $Source$, $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)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 success. (Severity: 3)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)Return value of "close" ignored at line 11, column 1. Check the return value of "close" for success. (Severity: 2)Return value of flagged function ignored - close at line 11, column 1. See pages 208,278 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)

• Can be configured

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 }

Configuration

• .perlcriticrc file

Configuration

• In home directory or project directory

Configuration

• In home directory or project directory

• INI-style syntax

# Global options hereseverity = 2pager = /usr/bin/lesscolor = 1

File: ~/.perlcriticrc

These will be the defaults, unless

overridden at the command-line

Configuration

USAGE: perlcritic FILENAME[jeff@callahan:/Users/jeff]$ perlcritic Bar.pm 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)

Default severity is now 2, as defined in .perlcriticrc file

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

Getting More Information

# Global options hereseverity = 2verbose = 8

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

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

File: ~/.perlcriticrc

Configuration

[jeff@callahan:/Users/jeff]$ perlcritic Bar.pm Bar.pm source OK

Now running with severity = 2, and

verbose = 8

Eleven Levels Of Verbosity

• Increasing levels of detail

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

• Some of the available details:

• Message, diagnostic (PBP pages), POD extract

• Line, column, file name, file path, severity

• Source code, PPI element, policy name

• Integrates with editor’s compile-mode (vim, emacs)Thursday, September 30, 2010

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

• ControlStructures::ProhibitUnreachableCode

• NamingConventions::ProhibitAmbiguousNames

• Subroutines::ProhibitExcessComplexity

• CodeLayout::RequireTidyCode

• RegularExpressions::ProhibitFixedStringMatches

• Documentation::RequirePodSections

Tips For Choosing Policies

Tips For Choosing Policies• Use --profile-proto option to generate your

first .perlcriticrc file.

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

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

• Disable or reconfigure Policies that you don’t agree with.

• Don’t try to do it all at once.

#!/usr/bin/perl

print “Hi\n” if $^O eq ‘darwin’;print “Hello\n” if $^O =~ /win/i;

Bending The Rules

#!/usr/bin/perl

Bending The Rules

• This would violate ProhibitPostfixControls

#!/usr/bin/perl

Bending The Rules

• This would violate ProhibitPostfixControls

• But we really like the way it reads

#!/usr/bin/perl

## no critic

## use critic

Bending The Rules

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

#!/usr/bin/perl

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

Bending The Rules

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

#!/usr/bin/perl

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

Bending The Rules

You can also specify exactly which Policies to disable

Perl::Critic Applied

$> perlcritic --verbose 8 MyModule.pm

#!/usr/bin/perl

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

As command-line tool...

As pragma...

Perl::Critic Applied

#!/usr/bin/perl

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

As test library...

Tips For Working With Legacy Code

• Use --statistics option to identify hotspots.

• Segregate new code from old code.

• Use “no critic” annotations around blocks of 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 first time.

• Makes a record of violations (in a local file).

• 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.

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

• Automatically loaded via Module::Pluggable.

• 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 conflict with existing ones.

• Policies can be general or domain-specific.

if ($foo && ($bar || $baz) || !($bar && $baz) || $qux) {...}

Suppose We Want To Ban Really Complex

Boolean Expressions...

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 Perl::Critic::Policy namespace

Policies organized by PBP table of contents

Some boilerplate

Extend the Policy baseclass

Define default attributes

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

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

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::Operator '&&' PPI::Token::Symbol '$baz' PPI::Structure::Block { ... }

How Does PPI See Your Code?

This is where we want to look for

violations

The offensive code 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

} As document is traversed, we get called each time a

PPI::Structure::Conditional is encountered

} We also get a reference to the entire document

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

sub violates {my ( $self, $elem, $doc ) = @_;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;

}Thursday, September 30, 2010

Search recursively for all Operators

Count those that are boolean

Using regex to determine type of operator

Return a violation if count exceeds maximum

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.

#----------------------------------------## 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) {}

File: t/ValuesAndExpressions/ProhbitComplexBoolean.run

Give test a name

How many violations to expect

Write offending code

Code region ends when next “## name” is found

Questions?

Thank You!

Jeffrey Thalhammer

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

jeff@imaginative-software.com

perl critic in depth

rcs keywords revision

genesis highly inconsistent

dont mix clean

extremely complicated code

verbosity increasing levels

default theme return qw

nasty legacy code

highly controversial severities

Documents

social compass meeting · web viewcontents council...

perl::critic and perl::tidy your guide to better programming...

perl/dbi - accessing databases from perl

readme - ibm · 2016. 7. 1. · openldap openssh...

dinner - cruise critic · dinner - cruise critic ... dinner...

critic curator

perl switches with the perl command

perl programming session 2 variables in perl

1 introduction to perl and perl syntax learning perl,...

the critic

yapc::na 2007 - customizing and extending perl critic

movie critic

perl practical extraction and report language. perl language...

jesus critic

an introduction to perl critic

research critic

critic spl

critic article

perl: a short introduction for bioinformaticians · perl: a...

cruise critic