vcs.maemo.org Git - dh-make-perl/blob - dev/arm/libperl-critic-perl/libperl-critic-perl-1.088/lib/Perl/Critic/Policy/Modules/ProhibitExcessMainComplexity.pm

   1 ##############################################################################
   2 #      $URL: http://perlcritic.tigris.org/svn/perlcritic/trunk/Perl-Critic/lib/Perl/Critic/Policy/Modules/ProhibitExcessMainComplexity.pm $
   3 #     $Date: 2008-07-03 10:19:10 -0500 (Thu, 03 Jul 2008) $
   4 #   $Author: clonezone $
   5 # $Revision: 2489 $
   6 ##############################################################################
   7
   8 package Perl::Critic::Policy::Modules::ProhibitExcessMainComplexity;
   9
  10 use 5.006001;
  11 use strict;
  12 use warnings;
  13 use Readonly;
  14
  15 use Perl::Critic::Utils qw{ :severities };
  16 use Perl::Critic::Utils::McCabe qw{ calculate_mccabe_of_main };
  17
  18 use base 'Perl::Critic::Policy';
  19
  20 #-----------------------------------------------------------------------------
  21
  22 our $VERSION = '1.088';
  23
  24 #-----------------------------------------------------------------------------
  25
  26 Readonly::Scalar my $EXPL => q{Consider refactoring};
  27
  28 #-----------------------------------------------------------------------------
  29
  30 sub supported_parameters {
  31     return (
  32         {
  33             name            => 'max_mccabe',
  34             description     => 'The maximum complexity score allowed.',
  35             default_string  => '20',
  36             behavior        => 'integer',
  37             integer_minimum => 1,
  38         },
  39     );
  40 }
  41
  42 sub default_severity { return $SEVERITY_MEDIUM                }
  43 sub default_themes   { return qw(core complexity maintenance) }
  44 sub applies_to       { return 'PPI::Document'                 }
  45
  46 #-----------------------------------------------------------------------------
  47
  48 sub violates {
  49     my ( $self, $doc, undef ) = @_;
  50
  51     my $score = calculate_mccabe_of_main( $doc );
  52
  53     # Is it too complex?
  54     return if $score <= $self->{_max_mccabe};
  55
  56     my $desc = qq{Main code has high complexity score ($score)};
  57     return $self->violation( $desc, $EXPL, $doc );
  58 }
  59
  60
  61 1;
  62
  63 __END__
  64
  65 #-----------------------------------------------------------------------------
  66
  67 =pod
  68
  69 =for stopwords McCabe
  70
  71 =head1 NAME
  72
  73 Perl::Critic::Policy::Modules::ProhibitExcessMainComplexity - Minimize complexity in code that is B<outside> of subroutines.
  74
  75 =head1 AFFILIATION
  76
  77 This Policy is part of the core L<Perl::Critic> distribution.
  78
  79
  80 =head1 DESCRIPTION
  81
  82 All else being equal, complicated code is more error-prone and more expensive
  83 to maintain than simpler code.  The first step towards managing complexity is
  84 to establish formal complexity metrics.  One such metric is the McCabe score,
  85 which describes the number of possible paths through a block of code.  This
  86 Policy approximates the McCabe score by summing the number of conditional
  87 statements and operators within a block of code.  Research has shown that a
  88 McCabe score higher than 20 is a sign of high-risk, potentially untestable
  89 code.  See L<http://www.sei.cmu.edu/str/descriptions/cyclomatic_body.html> for
  90 some discussion about the McCabe number and other complexity metrics.
  91
  92 Whereas L<Perl::Critic::Policy::Subroutines::ProhibitExcessComplexity> scores
  93 the complexity of each subroutine, this Policy scores the total complexity of
  94 all the code that is B<outside> of any subroutine declaration.
  95
  96 The usual prescription for reducing complexity is to refactor code into
  97 smaller subroutines.  Mark Dominus book "Higher Order Perl" also describes
  98 callbacks, recursion, memoization, iterators, and other techniques that help
  99 create simple and extensible Perl code.
 100
 101 =head1 CONFIGURATION
 102
 103 The maximum acceptable McCabe score can be set with the C<max_mccabe>
 104 configuration item.  If the sum of all code B<outside> any subroutine has a
 105 McCabe score higher than this number, it will generate a Policy violation.
 106 The default is 20.  An example section for a F<.perlcriticrc>:
 107
 108   [Modules::ProhibitExcessMainComplexity]
 109   max_mccabe = 30
 110
 111 =head1 NOTES
 112
 113
 114   "Everything should be made as simple as possible, but no simpler."
 115
 116                                                   -- Albert Einstein
 117
 118
 119 Complexity is subjective, but formal complexity metrics are still incredibly
 120 valuable.  Every problem has an inherent level of complexity, so it is not
 121 necessarily optimal to minimize the McCabe number.  So don't get offended if
 122 your code triggers this Policy.  Just consider if there B<might> be a simpler
 123 way to get the job done.
 124
 125 =head1 SEE ALSO
 126
 127 L<Perl::Critic::Policy::Subroutines::ProhibitExcessComplexity>
 128
 129 =head1 AUTHOR
 130
 131 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 132
 133 =head1 COPYRIGHT
 134
 135 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
 136
 137 This program is free software; you can redistribute it and/or modify
 138 it under the same terms as Perl itself.  The full text of this license
 139 can be found in the LICENSE file included with this module.
 140
 141 =cut
 142
 143 # Local Variables:
 144 #   mode: cperl
 145 #   cperl-indent-level: 4
 146 #   fill-column: 78
 147 #   indent-tabs-mode: nil
 148 #   c-indentation-style: bsd
 149 # End:
 150 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :