resources/checkstyle/README.txt

   1 Checkstyle for Jalview
   2 ----------------------
   3
   4 http://checkstyle.sourceforge.net/
   5 GNU LGPL
   6
   7 To get the Eclipse Checkstyle plugin
   8 ------------------------------------
   9         - Help | Eclipse Marketplace
  10         - search for checkstyle
  11         - install eclipse-cs checkstyle plugin
  12 The current version is 6.19.1 (August 2016).
  13
  14 Config
  15 ------
  16
  17         File Jalview/.checkstyle holds configuration for the "JalviewCheckstyle" ruleset.
  18         This includes confining its scope to src/*.java and resources/*.properties.
  19         This can be modified interactively through the checkstyle properties editor.
  20
  21         Checkstyle config files in resources/checkstyle:
  22                 checkstyle.xml          : main configuration file with selected checkstyle modules
  23                 checkstyle-suppress.xml : rules to exclude certain checks / files
  24                 import-control.xml      : package import rules
  25
  26         Checkstyle error messages can be customised. See TypeName for an example.
  27
  28 How to use checkstyle
  29 ---------------------
  30
  31         Option 1: enable it for the Jalview project
  32                 - right-click on project | Checkstyle | Activate Checkstyle
  33                 - notice CheckstyleNature gets added to the .project file
  34                 - don't commit this file unless we all agree to!
  35                 - Checkstyle will run as you recompile changed code
  36
  37         Option 2: on demand on selected code
  38                 - right-click on a class or package and Checkstyle | Check code with checkstyle
  39
  40 Checkstyle rules
  41 ----------------
  42         Documented at http://checkstyle.sourceforge.net/checks.html
  43         Should be self-documenting in checkstyle.xml
  44         Open for discussion:
  45         - which rules to use
  46         - what naming and layout standards to apply
  47         - settings for complexity metrics
  48         - whether any rules should report an error instead of a warning
  49
  50 Suppressing findings
  51 --------------------
  52         If there are warnings you judge it ok to suppress, your options are
  53         (from most global to most local scope):
  54         - remove the rule entirely
  55         - adjust its properties
  56         - add an entry in checkstyle-suppress.xml to skip the file for the rule
  57         - add comments around the reported source lines
  58                 // CHECKSTYLE.OFF: RuleName
  59                 source code here
  60                 // CHECKSTYLE.ON: RuleName
  61         The suppression should be as localised as possible, to avoid false negatives.
  62
  63 Tips
  64 ----
  65         Sometimes checkstyle needs a kick before it will refresh its findings.
  66         A whitespace edit in checkstyle.xml usually does this. There may be better ways.
  67
  68         Invalid configuration files may result in checkstyle failing with an error reported
  69         in the Eclipse log file.
  70         Help | Installation Details | Configuration takes you to a screen with a
  71         'View Error Log' button.
  72
  73         Sometimes checkstyle can fail silently. Try 'touching' (editing) config files, failing
  74         that, carefully check / back out / redo any recent changes to its config.
  75
  76         Putting <!-- XML comments --> inside a checkstyle <module> causes it to be ignored!
  77
  78         If a rule doesn't behave as you expected, read its documentation carefully, including
  79         the use and default value of any properties.
  80
  81         To highlight a single rule's findings, you could temporarily raise its severity to error.