NAME
Perl::Critic::StricterSubs - Perl::Critic plugin for stricter subroutine
checks
AFFILIATION
This module has no functionality, but instead contains documentation for
this distribution and acts as a means of pulling other modules into a
bundle. All of the Policy modules contained herein will have an
"AFFILIATION" section announcing their participation in this grouping.
DESCRIPTION
As a dynamic language, Perl doesn't require you to define subroutines
until run-time. Although this is a powerful feature, it can also be a
major source of bugs. For example, you might mistype the name of a
subroutine, or call a subroutine from another module without including
that module or importing that subroutine. And unless you have very good
test coverage, you might not know about these bugs until you have
already launched your code.
The Perl::Critic::Policy modules in this distribution are aimed at
reducing errors caused by invoking subroutines that are not defined.
Each Policy can be used separately. But when applied together, they
enforce a specific and deliberate coding style that minimizes the chance
of writing code that makes calls to undefined subroutines.
This coding style will not appeal to everyone. Some folks will surely
find this coding style to be too verbose or too restrictive. In
particular, importing via Exporter tags and pattern matching is
purposely not supported. But hopefully, these Policies will encourage
you to consciously consider the inherent trade-offs of your current
coding style.
LIMITATIONS
Perl::Critic is a static analyzer, so the Policies in this distro only
pertain to static subroutines. That is, subroutine calls that typically
look like one of these:
foo();
Bar::baz( $string );
Quux->new( @args );
At present, Perl::Critic cannot not know the class ancestry of any
particular object reference. Thus, the Policies in this distro do not
cover object methods, such as these:
$object->foo();
Still, it is difficult for Perl::Critic to know precisely which static
subroutines will be defined at run time. Therefore, these Policies are
expected to report some false violations. So you probably don't want to
use these Policies with Test::Perl::Critic or other frameworks that
expect 100% violation-free code. Instead, I suggest using these Policies
with the perlcritic command to perform ad hoc analysis of your code.
INCLUDED POLICIES
The following Policy modules are shipped in this distribution. See the
documentation within each module for details on its specific behavior.
Perl::Critic::Policy::Modules::RequireExplicitInclusion
If you refer to symbols in another package, you must explicitly include
that module. [Severity: 4]
Perl::Critic::Policy::Subroutines::ProhibitCallsToUndeclaredSubs
Unqualified subroutines must always be declared or explicitly imported
within the file. [Severity: 4]
Perl::Critic::Policy::Subroutines::ProhibitCallsToUnexportedSubs
Only allow calls to external subroutines that are named in @EXPORT or
@EXPORT_OK. [Severity: 4]
Perl::Critic::Policy::Subroutines::ProhibitExportingUndeclaredSubs
All subroutines named for @EXPORT or @EXPORT_OK must be defined in the
file. [Severity: 4]
Perl::Critic::Policy::Subroutines::ProhibitQualifiedSubDeclarations
Do not declare subroutines with fully-qualified names [Severity: 3]
CONFIGURATION
After installing the "Perl-Critic-StricterSubs" distro, all the included
Policies available to the Perl::Critic engine. The Policies in this
distro all belong to the "strictersubs" theme, so you can disable all of
them at once using either of these methods:
# In your .perlcriticrc file...
theme = no strictersubs
# With the perlcritic command-line...
$> perlcritic --theme='no stricter_subs' MyModule.pm
See "CONFIGURATION" in Perl::Critic section for more information about
configuring the Perl::Critic engine.
Each Policy in this distro may support additional configuration settings
that can be accessed through your .perlcriticrc file. See the perldoc in
each Policy for more details.
ACKNOWLEDGEMENTS
DEVELOPMENT of the "Perl-Critic-StricterSubs" distribution was financed
by a grant from The Mathworks (<http://mathworks.com>). The Perl::Critic
team sincerely thanks The Mathworks for their generous support of the
Perl community and open-source software.
AUTHOR
Jeffrey Ryan Thalhammer <thaljef@cpan.org>
COPYRIGHT
Copyright (c) 2007 Jeffrey Ryan Thalhammer. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. The full text of this license can
be found in the LICENSE file included with this module.