File Coverage

blib/lib/Perl/Critic/Policy/Bangs/ProhibitVagueNames.pm
Criterion Covered Total %
statement 48 50 96.0
branch 7 8 87.5
condition n/a
subroutine 10 11 90.9
pod 5 6 83.3
total 70 75 93.3


line stmt bran cond sub pod time code
1             package Perl::Critic::Policy::Bangs::ProhibitVagueNames;
2              
3 5     5   2831 use strict;
  5         14  
  5         117  
4 5     5   21 use warnings;
  5         10  
  5         123  
5 5     5   22 use Perl::Critic::Utils qw( :booleans :severities );
  5         11  
  5         222  
6 5     5   667 use base 'Perl::Critic::Policy';
  5         13  
  5         2136  
7              
8             our $VERSION = '1.12';
9              
10             #----------------------------------------------------------------------------
11              
12             sub supported_parameters {
13             return (
14             {
15 12     12 0 39084 name => 'names',
16             description => 'Words to prohibit as variable and subroutine names.',
17             behavior => 'string list',
18             default_string => 'data info var obj object tmp temp',
19             },
20             {
21             name => 'add_names',
22             description => 'Additional words to prohibit as variable and subroutine names.',
23             behavior => 'string list',
24             },
25             );
26             }
27              
28 21     21 1 210 sub default_severity { return $SEVERITY_MEDIUM }
29 0     0 1 0 sub default_themes { return qw( bangs readability ) }
30 7     7 1 52760 sub applies_to { return 'PPI::Statement::Variable', 'PPI::Statement::Sub' }
31              
32             =for stopwords whitespace
33              
34             =head1 NAME
35              
36             Perl::Critic::Policy::Bangs::ProhibitVagueNames - Don't use generic variable and subroutine names.
37              
38             =head1 AFFILIATION
39              
40             This Policy is part of the L<Perl::Critic::Bangs> distribution.
41              
42             =head1 DESCRIPTION
43              
44             Variables and subroutines should have descriptive names. Names like
45             C<$data> and C<$info> are completely vague.
46              
47             my $data = shift; # not OK.
48             my $userinfo = shift # OK
49              
50             See
51             L<http://www.oreillynet.com/onlamp/blog/2004/03/the_worlds_two_worst_variable.html>
52             for more of my ranting on this.
53              
54             By default, the following names are bad: data, info, var, obj, object, tmp, temp
55              
56             The checking of names is case-insensitive. C<$info> and C<$INFO> are equally bad.
57              
58             =head1 CONFIGURATION
59              
60             This policy has two options: C<names> and C<add_names>.
61              
62             =head2 C<names>
63              
64             To replace the list of vague names, specify them as a whitespace
65             delimited set of prohibited names.
66              
67             [Bangs::ProhibitVagueNames]
68             names = data count line next
69              
70             =head2 C<add_names>
71              
72             To add to the list of vague names, specify them as a whitespace
73             delimited set of prohibited names.
74              
75             [Bangs::ProhibitVagueNames]
76             add_names = foo bar bat
77              
78             =cut
79              
80             sub initialize_if_enabled {
81 9     9 1 21611 my ( $self, $config ) = @_;
82              
83 9         21 $self->{_names} = { %{ $self->{_names} }, %{ $self->{_add_names} } };
  9         36  
  9         39  
84              
85 9         36 return $TRUE;
86             }
87              
88              
89             sub violates {
90 26     26 1 643 my ( $self, $elem, $doc ) = @_;
91              
92 26         47 my @violations;
93              
94 26         51 my $type = ref($elem);
95 26 100       67 if ( $type eq 'PPI::Statement::Variable' ) {
    100          
    50          
96 22         71 for my $symbol ( $elem->symbols ) {
97             # Make $basename be the variable name with no sigils or namespaces.
98 25         1402 my $fullname = $symbol->canonical;
99 25         316 my $basename = $fullname;
100 25         99 $basename =~ s/^[\$@%]//;
101 25         53 $basename =~ s/.*:://;
102              
103 25         80 push( @violations, $self->_potential_violation( $symbol, $fullname, $basename, 'Variable' ) );
104             }
105             }
106             elsif ( $type eq 'PPI::Statement::Sub' ) {
107 3         11 my $fullname = $elem->name;
108 3         79 my $basename = $fullname;
109 3         9 $basename =~ s/.*:://;
110              
111 3         8 push( @violations, $self->_potential_violation( $elem, $fullname, $basename, 'Subroutine' ) );
112             }
113             elsif ( $type eq 'PPI::Statement::Scheduled' ) {
114             # Ignore BEGIN, INIT, etc
115             }
116             else {
117 0         0 die "Unknown type $type";
118             }
119              
120 26         3107 return @violations;
121             }
122              
123             sub _potential_violation {
124 28     28   48 my $self = shift;
125 28         51 my $symbol = shift;
126 28         45 my $fullname = shift;
127 28         51 my $basename = shift;
128 28         47 my $what = shift;
129              
130 28         60 $basename = lc $basename;
131              
132 28         46 foreach my $naughty ( keys %{ $self->{'_names'} } ) {
  28         108  
133 140 100       335 if ( $basename eq lc $naughty ) {
134 21         56 my $desc = qq{$what named "$fullname"};
135 21         49 my $expl = "$what names should be specific, not vague";
136 21         74 return $self->violation( $desc, $expl, $symbol );
137             }
138             }
139              
140 7         23 return;
141             }
142              
143             1;
144              
145             __END__
146             =head1 AUTHOR
147              
148             Andy Lester C<< <andy at petdance.com> >> from code by
149             Andrew Moore C<< <amoore at mooresystems.com> >>.
150              
151             =head1 ACKNOWLEDGMENTS
152              
153             Adapted from policies by Jeffrey Ryan Thalhammer <thaljef@cpan.org>,
154             Based on App::Fluff by Andy Lester, "<andy at petdance.com>"
155              
156             =head1 COPYRIGHT
157              
158             Copyright (c) 2006-2013 Andy Lester
159              
160             This library is free software; you can redistribute it and/or modify it
161             under the terms of the Artistic License 2.0.
162              
163             =cut