--- /dev/null
+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 resources/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. I've done this for TypeName as 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
+ - checking the whole project can be slow and may hang - not recommended for now
+
+ Option 2: on selected code
+ - right-click on a class or package and Checkstyle | Check code with checkstyle
+
+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 error instead of warning
+
+Gotchas
+-------
+ 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!
+
\ No newline at end of file