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