##############################################################################
#      $URL: http://perlcritic.tigris.org/svn/perlcritic/branches/Perl-Critic-1.xxx/lib/Perl/Critic/PolicySummary.pod $
#     $Date: 2007-09-02 20:07:03 -0500 (Sun, 02 Sep 2007) $
#   $Author: clonezone $
# $Revision: 1854 $
##############################################################################

=head1 NAME

Perl::Critic::PolicySummary - Description of the bundled Policy modules

=head1 DESCRIPTION

The following Policy modules are distributed with Perl::Critic.  The
Policy modules have been categorized according to the table of
contents in Damian Conway's book B<Perl Best Practices>.  Since most
coding standards take the form "do this..." or "don't do that...", I
have adopted the convention of naming each module C<RequireSomething>
or C<ProhibitSomething>.  Each Policy is listed here with its default
severity.  If you don't agree with the default severity, you can
change it in your F<.perlcriticrc> file.  See the documentation of
each module for its specific details.

=head1 POLICIES

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitBooleanGrep>

Use C<List::MoreUtils::any> instead of C<grep> in boolean context [Severity 2]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitComplexMappings>

Map blocks should have a single statement [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitLvalueSubstr>

Use 4-argument C<substr> instead of writing C<substr($foo, 2, 6) = $bar> [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitReverseSortBlock>

Forbid $b before $a in sort blocks [Severity 1]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect>

Use L<Time::HiRes> instead of something like C<select(undef, undef, undef, .05)> [Severity 5]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval>

Write C<eval { my $foo; bar($foo) }> instead of C<eval "my $foo; bar($foo);"> [Severity 5]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitStringySplit>

Write C<split /-/, $string> instead of C<split '-', $string> [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan>

Write C<< eval { $foo->can($name) } >> instead of C<UNIVERSAL::can($foo, $name)> [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa>

Write C<< eval { $foo->isa($pkg) } >> instead of C<UNIVERSAL::isa($foo, $pkg)> [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitVoidGrep>

Don't use C<grep> in void contexts. [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::ProhibitVoidMap>

Don't use C<map> in void contexts. [Severity 3]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep>

Write C<grep { $_ =~ /$pattern/ } @list> instead of C<grep /$pattern/, @list> [Severity 4]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap>

Write C<map { $_ =~ /$pattern/ } @list> instead of C<map /$pattern/, @list> [Severity 4]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::RequireGlobFunction>

Use C<glob q{*}> instead of <*> [Severity 5]

=head2 L<Perl::Critic::Policy::BuiltinFunctions::RequireSimpleSortBlock>

Sort blocks should have a single statement [Severity 3]

=head2 L<Perl::Critic::Policy::ClassHierarchies::ProhibitAutoloading>

AUTOLOAD methods should be avoided [Severity 3]

=head2 L<Perl::Critic::Policy::ClassHierarchies::ProhibitExplicitISA>

Employ C<use base> instead of C<@ISA> [Severity 3]

=head2 L<Perl::Critic::Policy::ClassHierarchies::ProhibitOneArgBless>

Write C<bless {}, $class;> instead of just C<bless {};> [Severity 5]

=head2 L<Perl::Critic::Policy::CodeLayout::ProhibitHardTabs>

Use spaces instead of tabs. [Severity 3]

=head2 L<Perl::Critic::Policy::CodeLayout::ProhibitParensWithBuiltins>

Write C<open $handle, $path> instead of C<open($handle, $path)> [Severity 1]

=head2 L<Perl::Critic::Policy::CodeLayout::ProhibitQuotedWordLists>

Write C<qw(foo bar baz)> instead of C<('foo', 'bar', 'baz')> [Severity 2]

=head2 L<Perl::Critic::Policy::CodeLayout::ProhibitTrailingWhitespace>

Don't use whitespace at the end of lines. [Severity 1]

=head2 L<Perl::Critic::Policy::CodeLayout::RequireConsistentNewlines>

Use the same newline through the source [Severity 4]

=head2 L<Perl::Critic::Policy::CodeLayout::RequireTidyCode>

Must run code through L<perltidy>. [Severity 1]

=head2 L<Perl::Critic::Policy::CodeLayout::RequireTrailingCommas>

Put a comma at the end of every multi-line list declaration, including the last one. [Severity 1]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitCStyleForLoops>

Write C<for(0..20)> instead of C<for($i=0; $i<=20; $i++)> [Severity 2]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse>

Don't write long "if-elsif-elsif-elsif-elsif...else" chains. [Severity 3]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitDeepNests>

Don't write deeply nested loops and conditionals. [Severity 2]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitMutatingListFunctions>

Don't modify C<$_> in list functions [Severity 5]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls>

Write C<if($condition){ do_something() }> instead of C<do_something() if $condition> [Severity 2]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks>

Write C<if(! $condition)> instead of C<unless($condition)> [Severity 2]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitUnreachableCode>

Don't write code after an unconditional C<die, exit, or next>.  [Severity 4]

=head2 L<Perl::Critic::Policy::ControlStructures::ProhibitUntilBlocks>

Write C<while(! $condition)> instead of C<until($condition)> [Severity 2]

=head2 L<Perl::Critic::Policy::Documentation::PodSpelling>

Check your spelling [Severity 1]

=head2 L<Perl::Critic::Policy::Documentation::RequirePodAtEnd>

All POD should be after C<__END__> [Severity 1]

=head2 L<Perl::Critic::Policy::Documentation::RequirePodSections>

Organize your POD into the customary sections. [Severity 2]

=head2 L<Perl::Critic::Policy::ErrorHandling::RequireCarping>

Use functions from L<Carp> instead of C<warn> or C<die>. [Severity 3]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitBacktickOperators>

Discourage stuff like C<@files = `ls $directory`> [Severity 3]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitBarewordFileHandles>

Write C<open my $fh, q{<}, $filename;> instead of C<open FH, q{<}, $filename;> [Severity 5]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitInteractiveTest>

Use prompt() instead of -t [Severity 5]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitJoinedReadline>

Use "local $/ = undef" or File::Slurp instead of joined readline [Severity 3]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitOneArgSelect>

Never write C<select($fh)> [Severity 4]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitReadlineInForLoop>

Write C<< while( $line = <> ){...} >> instead of C<< for(<>){...} >> [Severity 4]

=head2 L<Perl::Critic::Policy::InputOutput::ProhibitTwoArgOpen>

Write C<< open $fh, q{<}, $filename; >> instead of C<< open $fh, "<$filename"; >> [Severity 5]

=head2 L<Perl::Critic::Policy::InputOutput::RequireCheckedOpen>

Write C<< my $error = open $fh, $mode, $filename; >> instead of C<< open $fh, $mode, $filename; >> [Severity 3]

=head2 L<Perl::Critic::Policy::InputOutput::RequireCheckedClose>

Write C<< my $error = close $fh; >> instead of C<< close $fh; >> [Severity 3]

=head2 L<Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint>

Write C<print {$FH} $foo, $bar;> instead of C<print $FH $foo, $bar;> [Severity 1]

=head2 L<Perl::Critic::Policy::Miscellanea::ProhibitFormats>

Do not use C<format>. [Severity 3]

=head2 L<Perl::Critic::Policy::Miscellanea::ProhibitTies>

Do not use C<tie>. [Severity 2]

=head2 L<Perl::Critic::Policy::Miscellanea::RequireRcsKeywords>

Put source-control keywords in every file. [Severity 2]

=head2 L<Perl::Critic::Policy::Modules::ProhibitAutomaticExportation>

Export symbols via C<@EXPORT_OK> or C<%EXPORT_TAGS> instead of C<@EXPORT>.  [Severity 3]

=head2 L<Perl::Critic::Policy::Modules::ProhibitEvilModules>

Ban modules that aren't blessed by your shop. [Severity 5]

=head2 L<Perl::Critic::Policy::Modules::ProhibitExcessMainComplexity>

Minimize complexity in code that is B<outside> of subroutines. [Severity 3]

=head2 L<Perl::Critic::Policy::Modules::ProhibitMultiplePackages>

Put packages (especially subclasses) in separate files. [Severity 4]

=head2 L<Perl::Critic::Policy::Modules::RequireBarewordIncludes>

Write C<require Module> instead of C<require 'Module.pm'> [Severity 5]

=head2 L<Perl::Critic::Policy::Modules::RequireEndWithOne>

End each module with an explicitly C<1;> instead of some funky expression. [Severity 4]

=head2 L<Perl::Critic::Policy::Modules::RequireExplicitPackage>

Always make the C<package> explicit. [Severity 4]

=head2 L<Perl::Critic::Policy::Modules::RequireFilenameMatchesPackage>

Package declaration must match filename [Severity 5]

=head2 L<Perl::Critic::Policy::Modules::RequireVersionVar>

Give every module a C<$VERSION> number. [Severity 2]

=head2 L<Perl::Critic::Policy::NamingConventions::ProhibitAmbiguousNames>

Don't use vague variable or subroutine names like 'last' or 'record'. [Severity 3]

=head2 L<Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseSubs>

Write C<sub my_function{}> instead of C<sub MyFunction{}> [Severity 1]

=head2 L<Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseVars>

Write C<$my_variable = 42> instead of C<$MyVariable = 42> [Severity 1]

=head2 L<Perl::Critic::Policy::References::ProhibitDoubleSigils>

Write C<@{ $array_ref }> instead of C<@$array_ref> [Severity 2]

=head2 L<Perl::Critic::Policy::RegularExpressions::ProhibitCaptureWithoutTest>

Capture variable used outside conditional [Severity 3]

=head2 L<Perl::Critic::Policy::RegularExpressions::RequireExtendedFormatting>

Always use the C</x> modifier with regular expressions. [Severity 2]

=head2 L<Perl::Critic::Policy::RegularExpressions::RequireLineBoundaryMatching>

Always use the C</m> modifier with regular expressions. [Severity 3]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitAmpersandSigils>

Don't call functions with a leading ampersand sigil. [Severity 2]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitBuiltinHomonyms>

Don't declare your own C<open> function. [Severity 4]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitExcessComplexity>

Minimize complexity by factoring code into smaller subroutines. [Severity 3]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitExplicitReturnUndef>

Return failure with bare C<return> instead of C<return undef> [Severity 5]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitNestedSubs>

C<sub never { sub correct {} }> [Severity 5]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitManyArgs>

Too many arguments [Severity 3]

=head2 L<Perl::Critic::Policy::Subroutines::ProhibitSubroutinePrototypes>

Don't write C<sub my_function (@@) {}> [Severity 5]

=head2 L<Perl::Critic::Policy::Subroutines::ProtectPrivateSubs>

Prevent access to private subs in other packages [Severity 3]

=head2 L<Perl::Critic::Policy::Subroutines::RequireArgUnpacking>

Always unpack C<@_> first [Severity 4]

=head2 L<Perl::Critic::Policy::Subroutines::RequireFinalReturn>

End every path through a subroutine with an explicit C<return> statement. [Severity 4]

=head2 L<Perl::Critic::Policy::TestingAndDebugging::ProhibitNoStrict>

Prohibit various flavors of C<no strict> [Severity 5]

=head2 L<Perl::Critic::Policy::TestingAndDebugging::ProhibitNoWarnings>

Prohibit various flavors of C<no warnings> [Severity 4]

=head2 L<Perl::Critic::Policy::TestingAndDebugging::ProhibitProlongedStrictureOverride>

Don't turn off strict for large blocks of code [Severity 4]

=head2 L<Perl::Critic::Policy::TestingAndDebugging::RequireTestLabels>

Tests should all have labels [Severity 3]

=head2 L<Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict>

Always C<use strict> [Severity 5]

=head2 L<Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings>

Always C<use warnings> [Severity 4]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitCommaSeparatedStatements>

Don't use the comma operator as a statement separator. [Severity 4]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitConstantPragma>

Don't C<< use constant $FOO => 15 >> [Severity 4]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitEmptyQuotes>

Write C<q{}> instead of C<''> [Severity 2]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitEscapedCharacters>

Write C<"\N{DELETE}"> instead of C<"\x7F">, etc. [Severity 2]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitImplicitNewlines>

Use concatenation or HEREDOCs instead of literal line breaks in strings [Severity 3]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitInterpolationOfLiterals>

Always use single quotes for literal strings. [Severity 1]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitLeadingZeros>

Write C<oct(755)> instead of C<0755> [Severity 5]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitLongChainsOfMethodCalls>

Long chains of method calls indicate tightly coupled code [Severity 2]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitMismatchedOperators>

Don't mix numeric operators with string operands, or vice-versa. [Severity 3]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitMixedBooleanOperators>

Write C< !$foo && $bar || $baz > instead of C< not $foo && $bar or $baz> [Severity 4]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitNoisyQuotes>

Use C<q{}> or C<qq{}> instead of quotes for awkward-looking strings. [Severity 2]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitQuotesAsQuotelikeOperatorDelimiters>

Don't use quotes (C<'>, C<">, C<`>) as delimiters for the quote-like operators. [Severity 3]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitVersionStrings>

Don't use strings like C<v1.4> or C<1.4.5> when including other modules. [Severity 3]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::RequireInterpolationOfMetachars>

Warns that you might have used single quotes when you really wanted double-quotes. [Severity 1]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::RequireNumberSeparators>

Write C< 141_234_397.0145 > instead of C< 141234397.0145 > [Severity 2]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::RequireQuotedHeredocTerminator>

Write C< print <<'THE_END' > or C< print <<"THE_END" > [Severity 3]

=head2 L<Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator>

Write C< <<'THE_END'; > instead of C< <<'theEnd'; > [Severity 1]

=head2 L<Perl::Critic::Policy::Variables::ProhibitConditionalDeclarations>

Do not write C< my $foo = $bar if $baz; > [Severity 5]

=head2 L<Perl::Critic::Policy::Variables::ProhibitLocalVars>

Use C<my> instead of C<local>, except when you have to. [Severity 2]

=head2 L<Perl::Critic::Policy::Variables::ProhibitMatchVars>

Avoid C<$`>, C<$&>, C<$'> and their English equivalents. [Severity 4]

=head2 L<Perl::Critic::Policy::Variables::ProhibitPackageVars>

Eliminate globals declared with C<our> or C<use vars> [Severity 3]

=head2 L<Perl::Critic::Policy::Variables::ProhibitPerl4PackageNames>

Use double colon (::) to separate package name components instead of single quotes ('). [Severity 2]

=head2 L<Perl::Critic::Policy::Variables::ProhibitPunctuationVars>

Write C<$EVAL_ERROR> instead of C<$@> [Severity 2]

=head2 L<Perl::Critic::Policy::Variables::ProtectPrivateVars>

Prevent access to private vars in other packages [Severity 3]

=head2 L<Perl::Critic::Policy::Variables::RequireInitializationForLocalVars>

Write C<local $foo = $bar;> instead of just C<local $foo;> [Severity 3]

=head2 L<Perl::Critic::Policy::Variables::RequireLexicalLoopIterators>

Write C<for my $element (@list) {...}> instead of C<for $element (@list) {...}>

=head2 L<Perl::Critic::Policy::Variables::RequireLocalizedPunctuationVars>

Magic variables should be assigned as "local" [Severity 2]

=head2 L<Perl::Critic::Policy::Variables::RequireNegativeIndices>

Negative array index should be used [Severity 4]

=head1 AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

=head1 COPYRIGHT

Copyright (c) 2005-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.

=cut

##############################################################################
# Local Variables:
#   mode: cperl
#   cperl-indent-level: 4
#   fill-column: 78
#   indent-tabs-mode: nil
#   c-indentation-style: bsd
# End:
# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab :
