Login
Modify suggestion for Policy name that prohibits calling
[gknop/Perl-Critic.git] / TODO.pod
CommitLineData
9b8f64cf
CD
1# best viewed via "perldoc TODO.pod"
2
501ee198
JRT
3=pod
4
a73f4a71 5=for stopwords LHS RHS REFACTORINGS FH SVN stopwords
501ee198 6
dae851e8
JRT
7=head1 NAME
8
369abea9 9Perl::Critic::TODO - Things for Perl::Critic developers to do
dae851e8 10
2b7b1533 11
dae851e8 12=head1 SOURCE
daad783f
AL
13
14 #######################################################################
15 # $URL$
16 # $Date$
17 # $Author$
18 # $Revision$
19 #######################################################################
20
2b7b1533 21
de8cacdb
CD
22=head1 SEE ALSO
23
24Perl-Critic-More is a separate distribution for less-widely-accepted
ab1cd5d7 25policies. It contains its own TODO.pod.
de8cacdb 26
2b7b1533 27
daad783f
AL
28=head1 NEW FEATURES
29
2b7b1533 30=over
daad783f 31
8b5892fc 32=item * Report Safari sections in addition to book page numbers.
9bc546d7 33
2b7b1533 34
515a4fff
ES
35=item * Add --files-with-violations/-l and --files-without-violations/-L options to F<perlcritic>.
36
37Just print out file names. I could have used this at work when combined with
38C<--single-policy>.
39
40 gvim `perlcritic --single-policy QuotedWordLists -l`
41
42
0fe898d5
ES
43=item * Add a file Behavior.
44
45
46=item * Allow values of (at least) string-list Parameters to be specified in a file.
47
48For the benefit of PodSpelling, etc.
49
50
51=item * Enhance string-list Behavior to allow specification of delimiters.
52
53For things like RequirePodSections.
54
55
afceaa1d
ES
56=item * Add queries to --list option to F<perlcritic>.
57
58List Policies based upon severity, theme, and (what I want this second)
59applies_to.
60
d0e776fc
ES
61=item * Add --prohibit-unrestricted-no-critic option to F<perlcritic>.
62
63Requires C<## no critic> to take an argument:
64
65 ## no critic (SomePolicyPattern) # ok
66 ## no critic # not ok
67
e95460bd 68Can't be done as a regular Policy because any line that violated it would disable it.
d0e776fc 69
2b7b1533 70
ad5f2c12
ES
71=item * Support for C<#line 123 "filename"> directives.
72
73For code generators and template languages that allow inline Perl code.
74
96fa2db5
ES
75Yes, somebody has an in-house templating system where they've written a custom
76test module that extracts the perl code from a template and critiques it.
77
1d077d29
ES
78Actually, this would be useful for programs: Module::Build "fixes" shebang
79lines so that there's the bit about invoking perl if the program is attempted
80to be run by a Bourne shell, which throws the line numbers off when using
81Test::P::C on the contents of a C<blib> directory.
82
2b7b1533 83
a889d362
ES
84=item * Enhance statistics.
85
86- Blank line count
87
88- POD line count
89
90- Comment line count
91
92- Data section count
93
a889d362 94
afb00bb2
ES
95=item * Detect 5.10 source and enable stuff for that.
96
97For example, treat C<say> as equivalent to C<print>.
98
99
1d077d29
ES
100=item * Support a means of failing if a Policy isn't installed.
101
102For example, the self compliance test now depends upon a Policy in the More
103distribution.
104
105Something like using a "+" sign in front of the Policy name in its
106configuration block, analogous to the "-" sign used for disabling a policy,
107e.g. "C<[+Example::Policy]>".
108
109
d1d6429f
AL
110=back
111
2b7b1533 112
daad783f
AL
113=head1 BUGS/LIMITATIONS
114
2b7b1533 115=over
daad783f 116
daad783f
AL
117=item * NamingConventions::ProhibitAmbiguousNames
118
119Don't allow compound names with forbidden words, like "last_record".
120Allow forbidden words in RHS of variable declarations
121
fd5bd7b5
JRT
122Also, we should make it easeir to add (or delete) words from the
123forbbiden list.
124
2b7b1533 125
daad783f
AL
126=item * Subroutines::ProtectPrivateSubs
127
128Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
129difference between that and C<< $self->_foo() >>
130
2b7b1533 131
d1d6429f
AL
132=item * ErrorHandling::RequireCarping
133
63124782 134This should not complain about using C<warn> or C<die> if it's not in a
df88f751 135function, or if it's not in a non-main:: package.
d1d6429f 136
63124782 137Also, should allow C<die> when it is obvious that the "message" is a reference.
5c77583a 138
2b7b1533 139
4c542233
AL
140=item * RegularExpressions::ProhibitCaptureWithoutTest
141
142Allow this construct:
143
144 for ( ... ) {
145 next unless /(....)/;
146 if ( $1 ) {
147 ....
148 }
149 }
150
151Right now, P::C thinks that the C<$1> isn't legal to use because it's
152"outside" of the match. The thing is, we can only get to the C<if>
153if the regex matched.
dfe2eb3f 154 while ( $str =~ /(expression)/ )
4c542233 155
2b7b1533 156
d9abc689
JRT
157=item * CodeLayout::ProhibitParensWithBuiltins
158
159Some builtin functions (particularly those that take a variable number of
c296c678
ES
160scalar arguments) should probably get parentheses. This policy should be
161enhanced to allow the user to specify a list of builtins that are expempt
162from the policy.
d9abc689 163
2b7b1533 164
c59ac28c
ES
165=item * ValuesAndExpressions::ProhibitCommaSeparatedStatements
166
167Needs to check for C<scalar( something, something )>.
168
169
326d1973
ES
170=item * Variables::ProhibitPunctuationVars
171
172Needs to look inside strings. RT #35970.
173
174
96280e8c
ES
175=item * TestingAndDebugging::RequireUseWarnings
176
177Check for -w on the shbang line.
178
2b7b1533 179
365e3d9d
AL
180=back
181
2b7b1533 182
daad783f
AL
183=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
184
5331273a
ES
185=over
186
187=item * Modules::RequireUseVersion [405-406]
188
189=item * Modules::RequireThreePartVersion [405-406]
190
3dabcef1
ES
191=item * RegularExpressions::RequireDotMatchAnything [240-241]
192
5331273a 193=back
daad783f 194
2b7b1533 195
daad783f
AL
196=head1 NON-PBP POLICIES WANTED
197
2b7b1533 198=over
daad783f 199
45136ef4
ES
200=item * Documentation::RequireModuleAbstract
201
202Require a C<=head1 NAME> POD section with content that matches
203C<\A \s* [\w:]+ \s+ - \s+ \S>. The single hyphen is the important bit. Also,
204must be a single line.
205
be48b0c6
ES
206=item * Expressions::RequireFatCommasInHashConstructors
207
0b15f123
ES
208=item * ErrorHandling::RequireCheckOfEvalErrorAfterEval
209
77fa21bd
ES
210=item * Expressions::ProhibitDecimalWithBitwiseOperator
211
212=item * Expressions::ProhibitStringsWithBitwiseOperator
213
2b7b1533 214
3264a614
ES
215=item * InputOutput::ProhibitMagicDiamond
216
217Steal the idea from L<B::Lint>.
218
219
df88f751 220=item * TBD::AllProgramsNeedShebangs
d92d2828
AL
221
222Anything that is a program should have a shebang line. This includes .t files.
223
2b7b1533 224
daad783f
AL
225=item * BuiltInFunctions::RequireConstantSprintfFormat
226
2b7b1533 227
daad783f
AL
228=item * BuiltInFunctions::RequireConstantUnpackFormat
229
1cc04072 230L<http://diotalevi.isa-geek.net/~josh/yapc-lint/slides/slide5.html>
daad783f 231
2b7b1533 232
dfe2eb3f
JRT
233=item * Miscellanea::ProhibitObnoxiousComments
234
235Forbid excessive hash marks e.g. "#### This is a loud comment ####".
236Make the obnoxious pattern configurable
237
2b7b1533 238
dfe2eb3f
JRT
239=item * ValuesAndExpressions::RequireNotOperator
240
241Require the use of "not" instead of "!", except when this would contradict
242ProhibitMixedBooleanOperators. This may be better suited for
243Perl::Critic::More.
244
2b7b1533 245
dfe2eb3f
JRT
246=item * Modules::RequireExplicitImporting
247
248Require every C<use> statement to have an explicit import list. You could
249still get around this by calling C<import> directly.
250
2b7b1533 251
dfe2eb3f
JRT
252=item * Modules::ForbidImporting
253
254Require every C<use> to have an explicitly empty import list. This is for
255folks who like to see fully-qualified function names. Should probably provide
256a list of exempt modules (like FindBin);
257
2b7b1533 258
daad783f
AL
259=item * ControlStructures::ProhibitIncludeViaDo
260
261Forbid C<do "foo.pl">. Not sure about this policy name.
262
2b7b1533 263
daad783f
AL
264=item * Variables::ProhibitUseVars
265
f707b14a
CD
266Disallow C<use vars qw(...)> and require C<our $foo> instead. This
267contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
268before applying this policy. Low severity.
daad783f 269
2b7b1533 270
daad783f
AL
271=item * VariablesAndExpressions::ProhibitQuotedHashKeys
272
273Forbid quotes around hash keys, unless they are really needed. This
274is against what Damian says. Suggested by Adam Kennedy. Low
275severity.
276
2b7b1533 277
b589a229 278=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
279
280Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
281
2b7b1533 282
7eec5b31
ES
283=item * RegularExpressions::ProhibitSWSWSW
284
285Require C<split> instead of C<m/\s*\w*\s*\w*\s*/>. From MJD's Red Flags.
286
287
daad783f
AL
288=item * VariablesAndExpressions::RequireConstantVersion (low severity)
289
2b7b1533 290
f707b14a
CD
291=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
292
daad783f
AL
293L<http://rt.cpan.org/Ticket/Display.html?id=20439>
294
2b7b1533 295
79b72614
CD
296=item * Documentation::RequireSynopsis
297
2b7b1533 298
79b72614
CD
299=item * Documentation::RequireLicense
300
301These are simplified versions of Documentation::RequirePodSections.
302
2b7b1533 303
6a4d1045
CD
304=item * Documentation::RequireValidSynopsis
305
306The Synopsis section must be all indented and must be syntactically valid Perl
307(as validated by PPI).
308
2b7b1533 309
90c0067c
CD
310=item * Documentation::ProhibitEmptySections
311
312Any C<=headN> and C<=over> sections must not be empty. This helps catch
313boilerplate (althought Test::Pod should catch empty C<=over> blocks).
314
315On the other hand, C<=item ...> sections can be empty, since the item label is
316content.
317
2b7b1533 318
79b72614
CD
319=item * Miscellaneous::ProhibitBoilerplate
320
b589a229 321Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 322etc.
c6e7b236 323
ef919624
CD
324Here's a non-PPI implementation:
325L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
326
2b7b1533 327
956825ec
CD
328=item * BuiltinFunctions::ProhibitExtraneousScalarCall
329
330Recommend that C<if (scalar @array)> be rewritten as C<if (@array)>.
331
2b7b1533 332
6a4d1045
CD
333=item * RegularExpressions::ProhibitMixedDelimiters
334
335Ban s{foo}(bar)
336
2b7b1533 337
c79c8b5b
CD
338=item * RegularExpressions::ProhibitScalarAsRegexp
339
340Ban naked srtings as regexps, like:
341
342 print 1 if $str =~ $regexp;
343
344Instead, it should be:
345
346 print 1 if $str =~ m/$regexp/;
347
348or
349
350 print 1 if $str =~ m/$regexp/xms;
351
352
6a4d1045
CD
353=item * ValuesAndExpressions::RequireInterpolatedStringyEval
354
355Ensure that the argument to a stringy eval is not a constant string. That's
356just wasteful. Real world examples include:
357
358 eval 'use Optional::Module';
359
360which is better written as
361
362 eval { require Optional::Module; Optional::Module->import };
363
364for performance gains and compile-time syntax checking.
365
2b7b1533 366
76a987f3
CD
367=item * RegularExpressions::ProhibitUnnecessaryEscapes
368
369Complain if user puts a backslash escape in front of non-special characters. For example:
370
371 m/\!/;
372
373Make exceptions for C<\">, C<\'> and C<\`> since those are often inserted to
374workaround bugs in syntax highlighting.
375
376Note that this is different inside character classes, where only C<^>, C<]>
377and C<-> need to be escaped, I think. Caret only needs to be escaped at the
378beginning, and dash does NOT need to be escaped at the beginning and end. See
379L<perlreref>.
380
2b7b1533 381
fef95802
ES
382=item * Steal ideas from L<Dunce::Files>.
383
18658b1a
CD
384Can someone expand this entry, please?
385
386=item * ControlStructures::ProhibitAssigmentInConditional
387
388=item * ValuesAndExpressions::RequireConstantBeforeEquals
389
390=item * ValuesAndExpressions::RequireConstantBeforeOperator
391
392L<http://use.perl.org/~stu42j/journal/36412>
393
394Just about everyone has been bitten by C<if ($x = 10) { ... }> when they meant
395to use C<==>. A safer style is C<10 == $x> because omitting the second C<=>
396yields a noisy compile-time failure instead of silent runtime error.
397
398ProhibitAssigmentInConditional complains if the condition of a while, until,
399if or unless is solely an assignment. If it's anything more complex (like
400C<if (($x=10)){}> or C<while ($x=$y=$z){}>), there is no warning.
401
402RequireConstantBeforeEquals complains if the left side of an C<==> is a
403variable while the right side is a constant.
404
405RequireConstantBeforeOperator complains if the left side of any comparison
406operator (C<==>, C<eq>, C<&lt;>, etc) is a variable while the right side is a
407constant.
fef95802 408
3f64b6c8
ES
409
410=item * InputOutput::ProhibitUTF8IOLayer
411
412http://www.perlfoundation.org/perl5/index.cgi?the_utf8_perlio_layer
413
b61a141c 414=item * BuiltinFunctions::ProhibitExit(?:InModules)?
f0a7988d
CD
415
416Forbid C<exit()> in files that lack a shebang. Inspired by
417L<http://use.perl.org/~Ovid/journal/36746> and an analgous checker in
418FindBugs.
3f64b6c8 419
daad783f
AL
420=back
421
2b7b1533 422
daad783f
AL
423=head1 REFACTORINGS and ENHANCEMENTS
424
2b7b1533 425=over
daad783f 426
628facda
ES
427=item * Create constants for the PPI location array elements.
428
2b7b1533 429
992600be
JRT
430=item * MOVE THE LINE-DISABLING INTO P::C::Document
431
432All the code that deals with finding all the '##no critic' comments and noting
433which policies are disabled at each line seems like it would be better placed
434in Perl::Critic::Document. P::C::Document could then provide methods to
435indicate if a policy is disabled at a particular line. So the basic algorithm
436in Perl::Critic might look something like this:
437
438 foreach $element (@PPI_ELEMENTS) {
439 foreach $policy (@POLICIES) {
440 $line = $element->location->[0];
441 next if $doc->policy_is_disabled_at_line( $policy, $line );
442 push @violations, $policy->violates( $elem, $doc );
443 }
444 }
445
2b7b1533 446
aae75e29
ES
447=item * Some means of detecting "runnaway" C<##no critic>
448
449Elliot was talking to a couple of users at ETech and one of their major
450concerns was that they were using C<##no critic> and forgetting to do a
451C<##use critic> after the problematic section. Perhaps an option to
452F<perlcritic> to scan for such things is in order.
453
2b7b1533 454
dfe2eb3f
JRT
455=item * Change API to use named parameters
456
457Most of the methods on the public classes use named parameters for passing
458arguments. I'd like to extend that pattern to include all object-methods.
459Static methods can still use positional parameters.
460
2b7b1533 461
dfe2eb3f 462=item * Enhance P::C::critique() to accept files, directories, or code strings
501ee198 463
9b8f64cf 464Just like F<bin/perlcritic> does now.
daad783f 465
2b7b1533 466
9b8f64cf
CD
467=item * Add C<-cache> flag to F<bin/perlcritic>
468
469If enabled, this turns on L<PPI::Cache>:
470
471 require PPI::Cache;
472 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
473 mkdir $cache_path, oct 700 if (! -d $cache_path);
474 PPI::Cache->import(path => $cache_path);
475
de8cacdb 476This cachedir should perhaps include the PPI version number! At least
84e87307 477until PPI incorporates its own version number in the cache.
9b8f64cf 478
de8cacdb 479(see F<t/40_criticize.t> for a more robust implementation)
79b72614 480
2b7b1533 481
c5bd966c
JRT
482=item * Use hash-lookup instead of C<List::MoreUtils::any> function.
483
484In several places, Perl::Critic uses C<List::MoreUtils::any> to see if
485a string is a member of a list. Instead, I suggest using a named
486subroutine that does a hash-lookup like this:
487
488 my %logical_ops = hashify( qw( ! || && ||= &&= and or not ) );
489 sub is_logical_op { return exists $logical_ops{ $_[0] }; }
490
f2b8ca3f
ES
491Why?
492
2b7b1533
ES
493
494=item * Allow color output to work through a pipe.
495
496http://rt.cpan.org/Ticket/Display.html?id=30140
497
233e8deb
ES
498F<ack> now supports this.
499
2b7b1533 500
9b8f64cf
CD
501=back
502
503=head1 PPI BUGS
504
505We're waiting on the following bugs to get fixed in a CPAN release of PPI:
506
2b7b1533
ES
507
508=over
9b8f64cf 509
c38138ab 510=item Newlines
b589a229
CD
511
512PPI does not preserve newlines. That makes
c38138ab
CD
513CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
514now, it's implemented by pulling the source out of the file and skipping PPI.
515
516It's unlikely that PPI will support mixde newlines anytime soon.
517
2b7b1533 518
ef919624
CD
519=item Operators
520
521ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
522for PPI bugs with parsing operators. Many of these bugs have been
523fixed in PPI, so it would be good to check if those workarounds are
524still needed.
525
2b7b1533 526
6a4d1045
CD
527=item Regexp methods
528
529Not strictly a bug -- the PPI Regexp classes have a dearth of accessor methods
530as of v1.118, meaning that we have to do messy digging into internals. I
531wrote Perl::Critic:Utils::PPIRegexp to encapsulate this messiness, but it
532would be nicer to have an official interface in PPI.
533
2b7b1533 534
daad783f 535=back
501ee198 536
85e38a07 537=cut
dfe2eb3f
JRT
538
539##############################################################################
540# Local Variables:
541# mode: cperl
542# cperl-indent-level: 4
543# fill-column: 78
544# indent-tabs-mode: nil
545# c-indentation-style: bsd
546# End:
96fed375 547# ex: set ts=8 sts=4 sw=4 tw=78 ft=pod expandtab shiftround :