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 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.