+++ /dev/null
-Checkstyle for Jalview
-----------------------
-
-See
-https://issues.jalview.org/browse/JAL-1854
-http://checkstyle.sourceforge.net/
-GNU LGPL
-
-To get the Eclipse Checkstyle plugin
-------------------------------------
- - Help | Eclipse Marketplace
- - search for checkstyle
- - install eclipse-cs checkstyle plugin
-
-Change Log
-----------
-See http://checkstyle.sourceforge.net/releasenotes.html
-Aug 2016 Initial version used is 6.19.1
-Dec 2018 Updated to 8.12.0 (latest on Eclipse Marketplace, 8.15 is latest release)
- SuppressionCommentFilter relocated (changed in 8.1)
- FileContentsHolder removed (changed in 8.2)
- Updates to import-control.xml for code changes (htsjdk, stackoverflowusers)
-
-Config
-------
-
- File Jalview/.checkstyle holds configuration for the "JalviewCheckstyle" ruleset.
- This includes confining its scope to src/*.java and resources/*.properties.
- This can be modified interactively through the checkstyle properties editor.
-
- Checkstyle config files in utils/checkstyle:
- checkstyle.xml : main configuration file with selected checkstyle modules
- checkstyle-suppress.xml : rules to exclude certain checks / files
- import-control.xml : package import rules
-
- Checkstyle error messages can be customised. See TypeName for an example.
-
-How to use checkstyle
----------------------
-
- Option 1: enable it for the Jalview project
- - right-click on project | Checkstyle | Activate Checkstyle
- - notice CheckstyleNature gets added to the .project file
- - don't commit this file unless we all agree to!
- - Checkstyle will run as you recompile changed code
-
- Option 2: on demand on selected code
- - right-click on a class or package and Checkstyle | Check code with checkstyle
- - (or Clear Checkstyle violations to remove checkstyle warnings)
- - recommended to use this as a QA step when changing or reviewing code
-
-Checkstyle rules
-----------------
- Documented at http://checkstyle.sourceforge.net/checks.html
- Should be self-documenting in checkstyle.xml
- Open for discussion:
- - which rules to use
- - what naming and layout standards to apply
- - settings for complexity metrics
- - whether any rules should report an error instead of a warning
-
-Suppressing findings
---------------------
- If there are warnings you judge it ok to suppress (false positives),
- your options are (from most global to most local impact):
- - remove the rule entirely
- - adjust its properties
- - add an entry in checkstyle-suppress.xml to skip the file for the rule
- - add comments around the reported source lines
- // CHECKSTYLE.OFF: RuleName 'a comment to justify suppression'
- source code here
- // CHECKSTYLE.ON: RuleName
- The suppression should be as localised as possible, to avoid false negatives.
-
-Tips
-----
- Sometimes checkstyle needs a kick before it will refresh its findings.
- Click the 'refresh' icon at top right in Eclipse | Preferences | Checkstyle.
-
- Invalid configuration files may result in checkstyle failing with an error reported
- in the Eclipse log file.
- Eclipse | About | Installation Details | Configuration takes you to a screen with a
- 'View Error Log' button.
-
- Sometimes checkstyle can fail silently. Try 'touching' (editing) config files, failing
- that, carefully check / back out / redo any recent changes to its config.
-
- Putting <!-- XML comments --> inside a checkstyle <module> causes it to be ignored!
-
- If a rule doesn't behave as you expected, read its documentation carefully, including
- the use and default value of any properties.
-
- To highlight a single rule's findings, you can 'Configure Contents' of the Problems view
- and filter on Text Contains <rule name> (case-sensitive).
- Here you should select 'Use item limits' with a value of, say, 500, or Eclipse may
- labour to display all warnings.
git://source.jalview.org / jalview.git / blobdiff