JAL-1854 checkstyle relocated to /utils, newlines to Unix (?)

[jalview.git] / utils / checkstyle / README.txt

diff --git a/utils/checkstyle/README.txt b/utils/checkstyle/README.txt
new file mode 100644 (file)
index 0000000..119c68e
--- /dev/null
+++ b/utils/checkstyle/README.txt
@@ -0,0 +1,82 @@
+Checkstyle for Jalview
+----------------------
+
+http://checkstyle.sourceforge.net/
+GNU LGPL
+
+To get the Eclipse Checkstyle plugin
+------------------------------------
+       - Help | Eclipse Marketplace
+       - search for checkstyle
+       - install eclipse-cs checkstyle plugin
+The current version is 6.19.1 (August 2016).
+
+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)
+
+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.
+       A whitespace edit in checkstyle.xml usually does this. There may be better ways.
+       
+       Invalid configuration files may result in checkstyle failing with an error reported
+       in the Eclipse log file. 
+       Help | 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 could temporarily raise its severity to error.