untested new SwingJS-site.zip so that at least we all have the same one.
[jalview.git] / utils / checkstyle / checkstyle.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE module PUBLIC "-//Puppy Crawl//DTD Check Configuration 1.3//EN" "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
3 <!--
4         Jalview Checkstyle configuration file
5 -->
6 <module name="Checker">
7         <!-- Default severity is warning -->
8         <property name="severity" value="warning"/>
9         <property name="fileExtensions" value="java,properties"/>
10
11         <!-- 
12                 Add any metrics that you wish to suppress to the following file.
13         -->
14         <module name="SuppressionFilter">
15                 <property name="file" value="${basedir}/utils/checkstyle/checkstyle-suppress.xml"/>
16         </module>
17
18         <!-- 
19                 Allow suppression of rules by comments, e.g.:
20                 // CHECKSTYLE.OFF: ParameterNumber
21                 ..method declaration
22                 // CHECKSTYLE.ON: ParameterNumber
23         -->
24         <module name="SuppressionCommentFilter">
25                 <property name="offCommentFormat" value="CHECKSTYLE.OFF\: ([\w\|]+)"/>
26                 <property name="onCommentFormat" value="CHECKSTYLE.ON\: ([\w\|]+)"/>
27                 <property name="checkFormat" value="$1"/>
28         </module>
29
30         <!-- 
31                 Check language bundles have the same keys and no duplicates
32                 (ensure Checkstyle is configured to scan non-source files)
33          -->
34         <module name="Translation">
35                 <property name="fileExtensions" value="properties"/>
36                 <property name="baseName" value="^Messages.*$"/>
37         </module>
38         <module name="UniqueProperties">
39             <property name="fileExtensions" value="properties" />
40                 <property name="severity" value="error"/>
41         </module>
42
43         <!--
44                 Maximum line count for source files
45                 (note this can't be inside TreeWalker)
46         -->
47         <module name="FileLength">
48                 <property name="max" value="1200"/>
49                 <property name="fileExtensions" value="java"/>
50         </module>
51         
52         <module name="TreeWalker">
53
54                 <property name="tabWidth" value="4"/>
55
56                 <!-- 
57                         Enables parsing of suppressions comments
58                         see http://checkstyle.sourceforge.net/config_filters.html#SuppressionCommentFilter 
59                 -->
60                 <module name="FileContentsHolder"/>
61
62         <!-- ****************************** -->
63         <!--         NAMING STANDARDS       -->
64         <!-- ****************************** -->
65                 
66                 <!--
67                         Naming convention for member fields. Start with (optional) underscore, then
68                         lower case, then camel case; no internal underscores
69                 -->
70                 <module name="MemberName">
71                         <property name="format" value="^_?[a-z][a-zA-Z0-9]*$"/>
72                 </module>
73
74                 <!-- 
75                         Naming convention for methods. Start with (optional) underscore, then
76                         lower case, then camel case; no internal underscores
77                 -->
78                 <module name="MethodName">
79                         <property name="format" value="^_?[a-z]([a-zA-Z0-9]+)*$"/>
80                 </module>
81
82                 <!--
83                         Name pattern for local final variables.
84                 -->
85                 <module name="LocalFinalVariableName">
86                         <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
87                 </module>
88
89                 <!--
90                         Name pattern for local variables
91                 -->
92                 <module name="LocalVariableName">
93                         <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
94                 </module>
95                 
96                 <!--
97                         Name pattern for constants (static final fields)
98                 -->
99                 <module name="ConstantName">
100                         <property name="format" value="^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
101                 </module>
102
103                 <!--
104                         Name pattern for parameters (note no underscores allowed)
105                 -->
106                 <module name="ParameterName">
107                         <property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
108                 </module>
109                 
110                 <!--
111                         Name pattern for static (non-final) fields
112                 -->
113                 <module name="StaticVariableName">
114                         <property name="format" value="^[a-z][a-zA-Z0-9_]*$"/>
115                 </module>
116                 
117                 <!--
118                         Name pattern for classes
119                 -->
120                 <module name="TypeName">
121                         <property name="format" value="[A-Z][a-zA-Z0-9]*$"/>
122                         <property name="tokens" value="CLASS_DEF"/>
123                 </module>
124                 
125                 <!--
126                         Name pattern for interfaces. All interfaces names must end with 'I'.
127                         ** currently suppressed in checkstyle-suppress.xml **
128                 -->
129                 <module name="TypeName">
130                         <property name="id" value="InterfaceNaming"/>
131                         <property name="format" value="^[A-Z][a-zA-Z0-9]*I$"/>
132                         <property name="tokens" value="INTERFACE_DEF"/>
133                         <message key="name.invalidPattern" value="Interface names should end in a I"/>
134                 </module>
135
136                 <!--
137                         Java package name pattern 
138                 -->
139                 <module name="PackageName">
140                         <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
141                 </module>
142
143         <!-- ****************************** -->
144         <!--         LAYOUT AND STYLE       -->
145         <!-- ****************************** -->
146
147                 <!-- 
148                         Only one top level type per source file
149                 -->
150                 <module name="OuterTypeNumber"/>
151                 
152                 <!-- 
153                         Ensure a class has a package declaration
154                  -->
155                 <module name="PackageDeclaration"/>
156                 
157                 <!--
158                         see http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141855.html#1852
159                         1. Class (static) variables: public, protected, package, private
160                         2. Instance variables: public, protected, package, private
161                         3. Constructors
162                         4. Methods
163                  -->
164                 <module name="DeclarationOrder"/>
165                 
166                 <!-- 
167                         Modifier order should conform to JLS
168                         see http://checkstyle.sourceforge.net/config_modifier.html#ModifierOrder 
169                         public protected private abstract static final transient volatile synchronized native strictfp          
170                 -->
171                 <module name="ModifierOrder"/>
172                 
173                 <!-- 
174                         Declare variables in separate statements, for readability and bug avoidance
175                  -->
176                 <module name="MultipleVariableDeclarations"/>
177                 
178                 <!-- 
179                         Don't have more than one statement on a line
180                         (code formatting on save may enforce this anyway)
181                  -->
182                 <module name="OneStatementPerLine"/>
183
184                 <!-- 
185                         Declare variables close to their point of first use 
186                         (doesn't handle variables used inside loops very well) 
187                 -->
188                 <module name="VariableDeclarationUsageDistance">
189                         <property name="allowedDistance" value="5" />
190                         <message key="variable.declaration.usage.distance.extend"
191                                 value="Distance between declaration of ''{0}'' and its first use is {1}, suggested maximum is {2}. Consider moving, or make final if it may not be modified." />
192                 </module>
193         
194                 <!-- 
195                         Only use blocks within control statements 
196                 -->
197                 <module name="AvoidNestedBlocks" />
198
199                 <!-- 
200                         Require at least a comment within a block. 
201                         Note this will accept auto-generated // TODO comments, 
202                         (but they should be flagged up by the TodoComment rule) 
203                 -->
204                 <module name="EmptyBlock">
205                         <property name="option" value="text"/>
206                 </module>
207                 
208                 <!-- 
209                         Require braces round all code blocks within if/else/for/do/while 
210                 -->
211                 <module name="NeedBraces"/>
212                 
213                 <!--
214                         Disallow empty ';' statements
215                 -->
216                 <module name="EmptyStatement"/>
217
218                 <!-- 
219                         Maximum number of return statements for a method
220                 -->
221                 <module name="ReturnCount">
222                         <property name="max" value="4"/>
223                 </module>
224
225                 <!-- 
226                         Don't use modifiers in contexts where their value is not optional,
227                         for example all interface methods are always public
228                         see http://checkstyle.sourceforge.net/config_modifier.html#RedundantModifier
229                 -->
230                 <module name="RedundantModifier"/>
231                 
232                 <!-- 
233                         Variables whose value is not modified should be declared final, both to show the
234                     program's intent, and to  allow compiler optimisation
235                     ** currently suppressed in checkstyle-suppress.xml **
236                  -->            
237                 <module name="FinalLocalVariable">
238                         <property name="tokens" value="VARIABLE_DEF" />
239                 </module>
240
241                 <!-- 
242                         Disallows shorthand of assigning values within an expression 
243                 -->
244                 <module name="InnerAssignment"/>
245
246                 <!-- 
247                         Use Java style array declarations to assist in readability 
248                 -->
249                 <module name="ArrayTypeStyle"/>
250
251                 <!-- 
252                         Use L not l to define a long constant 
253                 -->
254                 <module name="UpperEll"/>
255
256         <!-- ****************************** -->
257         <!--           SIZE LIMITS          -->
258         <!-- ****************************** -->
259
260                 <!--
261                         Maximum line count for methods
262                 -->
263                 <module name="MethodLength">
264                         <property name="tokens" value="METHOD_DEF"/>
265                         <property name="max" value="50"/>
266                         <property name="countEmpty" value="false"/>
267                 </module>
268
269                 <!--
270                         Maximum statement count for methods, constructors,
271                         instance initialisation and static initialisation blocks
272                 -->
273                 <module name="ExecutableStatementCount">
274                         <property name="max" value="30"/>
275                         <property name="tokens" value="METHOD_DEF"/>
276                 </module>
277                 <module name="ExecutableStatementCount">
278                         <property name="max" value="30"/>
279                         <property name="tokens" value="CTOR_DEF"/>
280                 </module>
281                 <module name="ExecutableStatementCount">
282                         <property name="max" value="4"/>
283                         <property name="tokens" value="INSTANCE_INIT"/>
284                 </module>
285                 <module name="ExecutableStatementCount">
286                         <property name="id" value="NoStaticInitialization"/>
287                         <property name="max" value="0"/>
288                         <property name="tokens" value="STATIC_INIT"/>
289                 </module>
290
291                 <!--
292                         Maximum parameter count for methods 
293                 -->
294                 <module name="ParameterNumber">
295                         <property name="max" value="5"/>
296                 </module>
297
298                 <!--
299                         Maximum line length for anonymous inner classes
300                 -->
301                 <module name="AnonInnerLength">
302                         <property name="max" value="40"/>
303                 </module>
304
305         <!-- ****************************** -->
306         <!--            IMPORTS             -->
307         <!-- ****************************** -->
308
309                 <!-- 
310                         Ensures that there are no redundant or unused imports.
311                      Should be handled by Save actions if using Eclipse 
312                 -->
313                 <module name="RedundantImport"/>
314                 <module name="UnusedImports"/>
315
316                 <!--
317                         Disallow * imports; may also be enforced by IDE Save Actions
318                 -->
319                 <module name="AvoidStarImport"/>
320
321                 <!-- 
322                         Disallow import of sun.* packages as they are not portable 
323                 -->
324                 <module name="IllegalImport"/>
325
326                 <!--
327                         rules as to what packages each package may (not) import
328                         see http://checkstyle.sourceforge.net/config_imports.html#ImportControl 
329                 -->
330                 <module name="ImportControl">
331                     <property name="file" value="${basedir}/utils/checkstyle/import-control.xml"/>
332                         <property name="severity" value="error"/>
333                 </module>
334                 
335         <!-- ****************************** -->
336         <!--         CATCH and THROW        -->
337         <!-- ****************************** -->
338
339                 <!-- 
340                         Disallow catch of Exception, RunTimeException or Error 
341                 -->
342                 <module name="IllegalCatch"/>
343
344                 <!-- 
345                         Disallow throw of Exception, RunTimeException or Error 
346                 -->
347                 <module name="IllegalThrows"/>
348
349         <!-- ****************************** -->
350         <!--          CODING CHECKS         -->
351         <!-- ****************************** -->
352
353                 <!-- 
354                         Check for use of factory method rather than constructor for specified classes
355                         e.g. Boolean.valueOf(true) rather than new Boolean(true)
356                 -->
357                 <module name="IllegalInstantiation">
358                         <property name="classes" value="java.lang.Boolean"/>
359                 </module>
360                 
361                 <!--
362                         Check that "string".equals(value) is used rather than value.equals("string")
363                 -->
364                 <module name="EqualsAvoidNull"/>
365
366                 <!--
367                         Check that equals() and hashCode() are always overridden together
368                 -->
369                 <module name="EqualsHashCode"/>
370                 
371                 <!-- 
372                         Require switch statements to include a default 
373                 -->
374                 <module name="MissingSwitchDefault"/>
375                 
376                 <!-- 
377                         Check that switch default follows all case statements
378                  -->
379                 <module name="DefaultComesLast">
380                         <property name="severity" value="error"/>
381                 </module>
382                 
383                 <!-- 
384                         Disallows fall-through in switch statements 
385                         i.e. a case without a break, return, throw or continue 
386                         NB a comment with the words "fall[s] through" suppresses this message
387                  -->
388                 <module name="FallThrough">
389                         <property name="severity" value="error" />
390                 </module>
391                 
392                 <!-- 
393                         Warn if boolean expressions can be simplified 
394                 -->
395                 <module name="SimplifyBooleanExpression"/>
396
397                 <!-- 
398                         Warn if boolean return expressions can be simplified 
399                 -->
400                 <module name="SimplifyBooleanReturn"/>
401
402                 <!--
403                         Classes with only private constructors should be declared final
404                 -->
405                 <module name="FinalClass"/>
406                 
407                 <!-- 
408                         Classes with only static methods should not be instantiable,
409                         so should declare a private default constructor.
410                 -->
411                 <module name="HideUtilityClassConstructor"/>
412                 
413                 <!-- 
414                         An Interface should declare methods (do not use to define constants only) 
415                 -->
416                 <module name="InterfaceIsType"/>
417                 
418                 <!-- 
419                         Disallow public fields in classes (other than constants) 
420                 -->
421                 <module name="VisibilityModifier">
422                         <property name="packageAllowed" value="true"/>
423                         <property name="allowPublicImmutableFields" value="true"/>
424                 </module>
425                 
426                 <!-- 
427                         Checks that a local variable or a parameter does not shadow a field that is defined in the same class.
428                         Note this should also be configured as a compiler warning in the IDE. 
429                 -->
430                 <module name="HiddenField"/> 
431
432                 <!-- 
433                         Check that proper logging is used.
434                         This may be suppressed in the class that provides logging functions.
435                 -->
436                 <module name="RegexpSinglelineJava">
437                         <property name="id" value="NoSysout" />
438                         <property name="format" value="System\.out\.println"/>
439                         <property name="ignoreComments" value="true"/>
440                         <message key="regexp.exceeded" value="Should use jalview.bin.Cache.log for logging"/>
441                 </module>
442                 <module name="RegexpSinglelineJava">
443                         <property name="id" value="NoSyserr" />
444                         <property name="format" value="System\.err\.println"/>
445                         <property name="ignoreComments" value="true"/>
446                         <message key="regexp.exceeded" value="Should use jalview.bin.Cache.log for logging"/>
447                 </module>
448
449                 <!--
450                         Checks that classes that define a covariant equals() method also override 
451                         method equals(java.lang.Object).
452                  -->
453                 <module name="CovariantEquals"/>
454                 
455                 <!-- 
456                         Checks that there are no "magic numbers" (numeric literals) 
457                 -->
458                 <module name="MagicNumber">
459                         <property name="ignoreNumbers" value="-1,0,1,2"/>
460                 </module>
461                 
462                 <!-- 
463                         Check that  loop control variables are not modified inside the for block
464                  -->
465                 <module name="ModifiedControlVariable">
466                 </module>
467                 
468                 <!-- 
469                         Checks that string literals are not used with == or !=.
470                  -->
471                 <module name="StringLiteralEquality">
472                 </module>
473                 
474                 <!-- 
475                         Don't override clone - it never works! 
476                  -->
477                 <module name="NoClone"/>
478                 
479                 <!-- 
480                         Checks that clone() invokes super.clone()
481                         (for classes that break the NoClone rule)
482                  -->
483                 <module name="SuperClone"/>
484                 
485                 <!-- 
486                         Checks that finalize() invokes super.finalize()
487                  -->
488                 <module name="SuperFinalize"/>
489                 
490                 <!-- 
491                         Disallow assignment of parameters.
492                  -->
493                 <module name="ParameterAssignment"/>
494
495                 <!-- 
496                         Checks for multiple occurrences of the same string literal within a single file.
497                         NB - does not check for the same string in different files.
498                  -->
499                 <module name="MultipleStringLiterals">
500                         <property name="allowedDuplicates" value="1"/>
501                 </module>
502                 
503                 <!-- 
504                         Checks that exceptions are immutable (have only final fields)
505                  -->
506                 <module name="MutableException"/>
507                 
508                 <!-- 
509                         A general rule to check for source text tokens that shouldn't be there
510                         see http://checkstyle.sourceforge.net/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html
511                  -->
512                 <module name="IllegalToken">
513                    <property name="tokens" value="LITERAL_ASSERT"/>
514                 </module>
515
516         <!-- ****************************** -->
517         <!--           COMPLEXITY           -->
518         <!-- ****************************** -->
519                 
520                 <!-- 
521                         Restrict the number of number of &&, ||, &, |  and ^ in an expression.
522                         Note that the operators & and | are not only integer bitwise operators, they are also the 
523                         non-shortcut versions of the boolean operators && and ||.
524                  -->
525                 <module name="BooleanExpressionComplexity">
526                         <property name="max" value="3"/>
527                 </module>
528                 
529                 <!-- 
530                         This metric measures the number of instantiations of other classes within the given class. 
531                         The higher the DAC, the more complex the data structure of the system.
532                  -->
533                 <module name="ClassDataAbstractionCoupling">
534                         <property name="max" value="7"/>
535                 </module>
536                 
537                 <!-- 
538                         The number of other classes a class relies on. A high number indicates over-complex
539                         class interdependencies that might benefit from refactoring.
540                  -->
541                 <module name="ClassFanOutComplexity">
542                 <property name="max" value="10"/>
543         </module>
544                 
545                 <!-- 
546                         Checks cyclomatic complexity against a specified limit. The complexity is a measure 
547                         of the minimum number of possible paths through the source and therefore the number of required 
548                         tests. Consider re-factoring if at or above 10.
549                  -->
550                 <module name="CyclomaticComplexity">
551                         <property name="max" value="15"/>
552                 </module>
553                 
554                 <!-- 
555                         The NPATH metric computes the number of possible execution paths through a function. It takes 
556                         into account the nesting of conditional statements and multi-part boolean expressions 
557                         (e.g., A && B, C || D, etc.).
558                  -->
559                 <module name="NPathComplexity">
560                         <property name="max" value="200"/>
561                 </module>
562
563                 <!-- 
564                         Maximum number of throws statements in a method
565                  -->
566                 <module name="ThrowsCount">
567                         <property name="max" value="2"/>
568                 </module>
569                 
570                 <!-- 
571                         Maximum if-else depth
572                  -->
573                 <module name="NestedIfDepth">
574                         <property name="max" value="4"/>
575                 </module>
576
577                 <!-- 
578                         Restricts nested try blocks to a specified depth. 
579                  -->
580                 <module name="NestedTryDepth">
581                         <property name="max" value="2"/>
582                 </module>
583
584         <!-- ****************************** -->
585         <!--              TODO              -->
586         <!-- ****************************** -->
587
588                 <!-- 
589                         Checks for uncommented main() methods (debugging leftovers)
590                  -->
591                 <module name="UncommentedMain"/>
592
593                 <!-- 
594                         Check for TODO and similar comments 
595                 -->
596                 <module name="TodoComment">
597                         <property name="format" value="(TODO)|(FIXME)"/>
598                         <message key="todo.match" value="TODO or FIXME comment"/>
599                 </module>
600
601                 <module name="TodoComment">
602                         <property name="format" value="DOCUMENT ME"/>
603                         <message key="todo.match" value="Documentation incomplete"/>
604                 </module>
605
606         </module>
607 </module>