JAL-2758 typo
[jalview.git] / utils / checkstyle / README.txt
1 Checkstyle for Jalview
2 ----------------------
3
4 http://checkstyle.sourceforge.net/
5 GNU LGPL
6
7 To get the Eclipse Checkstyle plugin
8 ------------------------------------
9         - Help | Eclipse Marketplace
10         - search for checkstyle
11         - install eclipse-cs checkstyle plugin
12 The current version is 6.19.1 (August 2016).
13
14 Config
15 ------
16
17         File Jalview/.checkstyle holds configuration for the "JalviewCheckstyle" ruleset.
18         This includes confining its scope to src/*.java and resources/*.properties.
19         This can be modified interactively through the checkstyle properties editor.
20         
21         Checkstyle config files in utils/checkstyle:
22                 checkstyle.xml          : main configuration file with selected checkstyle modules
23                 checkstyle-suppress.xml : rules to exclude certain checks / files
24                 import-control.xml      : package import rules
25         
26         Checkstyle error messages can be customised. See TypeName for an example.
27
28 How to use checkstyle
29 ---------------------
30
31         Option 1: enable it for the Jalview project
32                 - right-click on project | Checkstyle | Activate Checkstyle
33                 - notice CheckstyleNature gets added to the .project file
34                 - don't commit this file unless we all agree to!
35                 - Checkstyle will run as you recompile changed code
36
37         Option 2: on demand on selected code
38                 - right-click on a class or package and Checkstyle | Check code with checkstyle
39                 - (or Clear Checkstyle violations to remove checkstyle warnings)
40
41 Checkstyle rules
42 ----------------
43         Documented at http://checkstyle.sourceforge.net/checks.html
44         Should be self-documenting in checkstyle.xml
45         Open for discussion:
46         - which rules to use
47         - what naming and layout standards to apply
48         - settings for complexity metrics
49         - whether any rules should report an error instead of a warning  
50         
51 Suppressing findings
52 --------------------
53         If there are warnings you judge it ok to suppress (false positives), 
54         your options are (from most global to most local impact):
55         - remove the rule entirely
56         - adjust its properties
57         - add an entry in checkstyle-suppress.xml to skip the file for the rule
58         - add comments around the reported source lines
59                 // CHECKSTYLE.OFF: RuleName 'a comment to justify suppression'
60                 source code here
61                 // CHECKSTYLE.ON: RuleName
62         The suppression should be as localised as possible, to avoid false negatives.
63         
64 Tips
65 ----
66         Sometimes checkstyle needs a kick before it will refresh its findings.
67         A whitespace edit in checkstyle.xml usually does this. There may be better ways.
68         
69         Invalid configuration files may result in checkstyle failing with an error reported
70         in the Eclipse log file. 
71         Help | Installation Details | Configuration takes you to a screen with a 
72         'View Error Log' button.
73         
74         Sometimes checkstyle can fail silently. Try 'touching' (editing) config files, failing
75         that, carefully check / back out / redo any recent changes to its config.
76         
77         Putting <!-- XML comments --> inside a checkstyle <module> causes it to be ignored!
78         
79         If a rule doesn't behave as you expected, read its documentation carefully, including
80         the use and default value of any properties.
81         
82         To highlight a single rule's findings, you can 'Configure Contents' of the Problems view
83         and filter on Text Contains <rule name> (case-sensitive). 
84         Here you should select 'Use item limits' with a value of, say, 500,     or Eclipse may 
85         labour to display all warnings.