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