Login
fixed spacing on a verbatim paragraph
[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
f7231315 9TODO - 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
20=head1 NEW FEATURES
21
22=over 4
23
8b5892fc 24=item * Report Safari sections in addition to book page numbers.
9bc546d7 25
c6e7b236 26=item * Report some statistics on the violations and the source code.
d1d6429f 27
c6e7b236
JRT
28e.g. Number of violations of each policy/severity. Total lines of code,
29number of subroutines, average number of statements/operators per sub.
d1d6429f
AL
30
31=back
32
daad783f
AL
33=head1 BUGS/LIMITATIONS
34
35=over 4
36
0ab066f7
JRT
37=item * Invalid policy names in .perlcriticrc do not cause any warnings.
38
39=item * Invalid parameters in .perlcriticrc do not cause any warnings.
daad783f
AL
40
41=item * Modules::RequireVersionVar
42
43Doesn't enforce three-part versions
44
45=item * NamingConventions::ProhibitAmbiguousNames
46
47Don't allow compound names with forbidden words, like "last_record".
48Allow forbidden words in RHS of variable declarations
49
50=item * Subroutines::ProtectPrivateSubs
51
52Doesn't forbid C<< $pkg->_foo() >> because it can't tell the
53difference between that and C<< $self->_foo() >>
54
d1d6429f
AL
55=item * ErrorHandling::RequireCarping
56
ef919624
CD
57This should not complain about using warn or die if it's not in a
58function.
d1d6429f 59
5c77583a
AL
60Also, if the error string ends with a "\n", then the line number
61and package information is not shown, so it doesn't matter if you
62use carp/confess or not. For example:
63
64 my $fh;
65 if ( !open( $fh, '<', $filename ) ) {
66 warn "ack: $filename: $!\n";
67 return;
68 }
69
70I just want to print a warning and move on. The location is irrelevant.
71
365e3d9d
AL
72=back
73
daad783f
AL
74=head1 OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
75
365e3d9d
AL
76=over 4
77
0ab066f7
JRT
78
79=item * ControlStructures::ProhibitComplexMappings (p113)
80
81Base this on RequireSimpleSortBlock. Make number of statements configurable
82
daad783f
AL
83=item * ValuesAndExpressions::ProhibitCommaSeparatedStatements (p68)
84
85=item * ValuesAndExpressions::RequireListParens (p71)
86
87=item * ValuesAndExpressions::ProhibitScalarGrep (p71)
88
71cb5eb8
CD
89Look for grep in a scalar context and recommend any() instead.
90Perhaps we need to distinguish cases like:
7e9a4c52
AL
91
92 $count += grep {qr/foo/} @list;
daad783f
AL
93
94=item * Variables::RequireLocalizedPunctuationVars (p81)
95
daad783f
AL
96=item * Variables::ProhibitTopicChangeInListFunction (p114)
97
98=item * Documentation::PodSpelling (p148)
99
100Base it on Pod::Spell or Test::Spelling. Add a "=for stopwords"
101section for words to skip, as per Pod::Spell.
102
daad783f
AL
103=item * Subroutines::RequireArgUnpacking (p178)
104
105Ensure that the first child of a sub is PPI::Statement::Variable
71cb5eb8 106(unless the sub has N or fewer statements, where N defaults to 1.
daad783f
AL
107
108=item * Subroutines::ProhibitManyArgs (p182)
109
71cb5eb8
CD
110If first L<PPI::Statement::Variable> is a list C<my>, and @_ is used,
111make sure it's fewer than N elements. Otherwise make sure there are
112less than N L<PPI::Statement::Variable>s in a row at begin which
113shift.
daad783f
AL
114
115=item * InputOutput::RequireErrorChecking (p208)
116
71cb5eb8
CD
117Forbid open, print, close in void context, unless "use Fatal" is in
118effect.
daad783f
AL
119
120=item * InputOutput::RequireBriefOpen (p209)
121
122Make sure there's a close within N statements of an open, both with
123same lexical FH
124
125=item * InputOutput::ProhibitJoinedReadline (p213)
126
127=item * InputOutput::ProhibitExplicitStdin (p216)
128
daad783f
AL
129=item * Miscellanea::ProhibitObnoxiousComments
130
131Forbid excessive hash marks e.g. "#### This is a loud comment ####".
132Make the obnoxious pattern configurable
133
134=item * RegularExpressions::RequireBracesForMultiline (p242)
135
136=item * RegularExpressions::ProhibitUnusualDelimiters (p246)
137
138=item * RegularExpressions::ProhibitEscapedMetacharacters (p247)
139
140=item * RegularExpressions::ProhibitEnumeratedClasses (p248)
141
142This will be avoided for ASCII-only code
143
144=item * RegularExpressions::ProhibitUnusedCapture (p252)
145
146Look for LHS of regexp or use of C<$1>, C<$2>, ... before next
147regexp
148
daad783f
AL
149=item * RegularExpressions::ProhibitComplexRegexps (p261)
150
151If regexp is longer than N characters/lines, require it be split
152into C<qr//> pieces.
153
154=item * RegularExpressions::ProhibitSingleCharAlternation (p265)
155
156Not sure if this is easy or hard. Need to look at what PPI emits
1fd10f9b 157for regexps. Make an exception for qr/ [ ] /x.
daad783f
AL
158
159=item * RegularExpressions::ProhibitFixedStringMatches (p271)
160
161Can't be C<qr/\s*\\A\s*\((?:\?:)?(?:\s*\w+\s*\|)*\s*\w+\s*\)\s*\\z/>
162or C<qr/\s*\\A\s*\w+\s*\\z/>
163
164=item * TestingAndDebugging::ProhibitProlongedStrictureOverride (p443)
165
71cb5eb8
CD
166This conflicts with TestingAndDebugging::ProhibitNoStrict
167
daad783f
AL
168=back
169
170=head1 NON-PBP POLICIES WANTED
171
172=over 4
173
d92d2828
AL
174=item AllProgramsNeedShebangs
175
176Anything that is a program should have a shebang line. This includes .t files.
177
daad783f
AL
178=item * BuiltInFunctions::RequireConstantSprintfFormat
179
180=item * BuiltInFunctions::RequireConstantUnpackFormat
181
182L<http://home.earthlink.net/~josh.jore/new-warnings/slides/slide1.html>
183
184=item * ControlStructures::ProhibitIncludeViaDo
185
186Forbid C<do "foo.pl">. Not sure about this policy name.
187
b589a229 188=item * CodeLayout::ProhibitNonASCII
daad783f
AL
189
190Definitely low severity! Only looks at code, not comments or POD
191
b589a229 192=item * CodeLayout::RequireUTF8
79b72614
CD
193
194All characters must be valid UTF-8. Note that typical ASCII Perl code
195is a valid UTF8 subset.
196
daad783f
AL
197=item * Miscellanea::RequireMinimumPerlVersion
198
199Every module should have something like C<use 5.6.0>
200
201=item * Miscellanea::Prohibit5006isms
202
f707b14a 203Keep the code 5.005 compatible. Low severity
daad783f
AL
204
205=item * Variables::ProhibitUseVars
206
f707b14a
CD
207Disallow C<use vars qw(...)> and require C<our $foo> instead. This
208contradicts Miscellanea::Prohibit5006isms. Maybe verify C<use 5.6>
209before applying this policy. Low severity.
daad783f
AL
210
211=item * VariablesAndExpressions::ProhibitQuotedHashKeys
212
213Forbid quotes around hash keys, unless they are really needed. This
214is against what Damian says. Suggested by Adam Kennedy. Low
215severity.
216
217=item * Miscellanea::B::Lint
218
219Create a compatibility layer for the L<B::Lint> code analyzer. Make
220it very clear that this runs code and thus is a security hole.
221
b589a229 222=item * CodeLayout::ProhibitFunctionalNew
daad783f
AL
223
224Good: C<< Foo::Bar->new >>, Bad: C<< new Foo::Bar >>
225
226=item * VariablesAndExpressions::RequireConstantVersion (low severity)
227
f707b14a
CD
228=item * VariablesAndExpressions::ProhibitComplexVersion (medium severity)
229
daad783f
AL
230L<http://rt.cpan.org/Ticket/Display.html?id=20439>
231
c6e7b236
JRT
232=item * Variables::ProhibitPerl4PackageNames
233
b589a229 234Forbid old-school package names like Foo'Bar'Baz. This should also
c6e7b236
JRT
235apply to any variables or subroutines that get declared/called.
236
b589a229 237=item * CodeLayout::RequireEditorSettings
79b72614
CD
238
239Files must have something like the following in them for Emacs and Vi:
240
241 # Local Variables:
242 # mode: cperl
243 # cperl-indent-level: 4
c38138ab 244 # fill-column: 78
79b72614
CD
245 # End:
246 # vim: expandtab shiftwidth=4:
247
b589a229
CD
248=over 4
249
250=item Emacs file variables
251
252L<http://www.gnu.org/software/emacs/manual/html_node/File-Variables.html>
253
254In emacs, this is called "File Variables". There are two syntaxes:
255C<-*- ... -*-> (single-line) and C<Local Variables:\n...\nEnd:>
256(multi-line). Both syntaxes allow leading and trailing text on the
257line.
258
259The single-line syntax must be used on the first line of the file to
260be recognized.
261
262The multi-line syntax must be used "in the last page" at the end of
263the file. As of Emacs21, this is hard-coded to be the last 3000 bytes
264of the file (in the hack-local-variables function in files.el). In
265this syntax, each line must begin and end with the same prefix/suffix
266pair. That pair is defined by the text before and after the "Local
267Variables:" string.
268
269=item Vim modelines
270
271In vim, this is called "modelines" and should match the following
272pattern:
273
274 [text]{white}{vi:|vim:|ex:}[white]se[t] {options}:[text]
275
276The vim modeline must be within N lines of the top or bottom of the
277file. That N is user-settable, but defaults to 5. To learn more type
278":help modelines" in vim.
279
280=item Kate modelines
281
282I also discovered that Kate supports per-file modelines:
283
284L<http://kate-editor.org/article/katepart_modelines>
285
286=back
287
79b72614
CD
288=item * Documentation::RequireSynopsis
289
290=item * Documentation::RequireLicense
291
292These are simplified versions of Documentation::RequirePodSections.
293
79b72614
CD
294=item * Miscellaneous::ProhibitBoilerplate
295
b589a229 296Complain about copy-and-paste code or docs from h2xs, Module::Starter::*,
79b72614 297etc.
c6e7b236 298
ef919624
CD
299Here's a non-PPI implementation:
300L<http://search.cpan.org/src/JJORE/Carp-Clan-5.8/t/04boilerplate.t>
301
c38138ab
CD
302=item * ValuesAndExpressions::ProhibitHereDocs
303
304=item * ValuesAndExpressions::ProhibitLongStrings
305
306Low severity.
307
308Both of these attempt to address problems with code layout and appearance.
309Large blocks of inline text can disrupt the readability of code. Instead, the
310text should be external, in __DATA__, or simply declared in separate functions
311at the end of the module.
312
313Exceptions: if the only code in a sub is a return of a long string, allow it.
314If there is a C<use Inline::> at the top of the module, allow HereDocs.
315
316L<http://rt.cpan.org/Ticket/Display.html?id=20714>
317
318=item * CodeLayout::ProhibitTrailingSpaces
319
320Forbid [ \t] before \n. This is a subset of RequireTidyCode.
321
322L<http://rt.cpan.org/Ticket/Display.html?id=20714>
323
daad783f
AL
324=back
325
326=head1 REFACTORINGS and ENHANCEMENTS
327
328=over 4
329
daad783f
AL
330=item * Alias -verbose to -format option in Test::P::C.
331
332Give it same functionality as the -verbose option in `perlcritic`
333
501ee198
JRT
334=item * Enhance P::C::critique() to accept file names, directories, or code strings (as refs)
335
9b8f64cf 336Just like F<bin/perlcritic> does now.
daad783f 337
9b8f64cf
CD
338=item * Add C<-cache> flag to F<bin/perlcritic>
339
340If enabled, this turns on L<PPI::Cache>:
341
342 require PPI::Cache;
343 my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
344 mkdir $cache_path, oct 700 if (! -d $cache_path);
345 PPI::Cache->import(path => $cache_path);
346
347(see F<t/40_criticize.t> for a more robust implementation)
348
79b72614
CD
349=item * File::RequirePortableName
350
351No spaces, punctuation, etc.
352
9b8f64cf
CD
353=back
354
355=head1 PPI BUGS
356
357We're waiting on the following bugs to get fixed in a CPAN release of PPI:
358
359=over 4
360
b589a229
CD
361=item literal()
362
363ValuesAndExpressions::RequireNumberSeparators uses a stringy eval to
364numify. Current PPI SVN has code for the
365PPI::Token::Number->literal() method which numifies from source. When
366we depend on a PPI version higher than 1.118, the _to_number()
367function in that policy can be removed in favor of literal().
368
c38138ab 369=item Newlines
b589a229
CD
370
371PPI does not preserve newlines. That makes
c38138ab
CD
372CodeLayout::RequireConsistentNewlines impossible to implement under PPI. For
373now, it's implemented by pulling the source out of the file and skipping PPI.
374
375It's unlikely that PPI will support mixde newlines anytime soon.
376
377=item Anonymous constructors in lists
378
379The following parses wrong in PPI v1.118. A PPI fix is in progress.
380
381 bless( {} );
382
383When this is fixed, uncomment a few tests in t/20_policies_classhierarchies.t
b589a229 384
ef919624
CD
385=item Operators
386
387ValuesAndExpressions::ProhibitMismatchedOperators has two workarounds
388for PPI bugs with parsing operators. Many of these bugs have been
389fixed in PPI, so it would be good to check if those workarounds are
390still needed.
391
daad783f 392=back
501ee198 393
85e38a07 394=cut