File Coverage

blib/lib/Perl/Critic/Policy/Modules/ProhibitExcessMainComplexity.pm
Criterion Covered Total %
statement 29 29 100.0
branch 2 2 100.0
condition n/a
subroutine 12 12 100.0
pod 4 5 80.0
total 47 48 97.9


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