IT Mill Toolkit Coding Conventions

We use UTF-8.

We follow Code Conventions for the Java Programming Language (Mandatory read!)

Format (ctrl-shift-F) and Organize Imports (ctrl-shift-O) before commit, or even better: as Save Actions. Formatting might uncover problems with your code, so you might want to do it every now and then while coding.

Clean Up can be found under the Source -menu. Consider doing that before commit.

Eclipse setup

1. Text File Encoding

1.1. Workspace-wide: Window->Preferences->General->Workspace

  • Text File Encoding, Other: UTF-8

or

Project specific: Properties->Resource

  • Text File Encoding, Other: UTF-8

2. JDK compliance

For now, we want all code committed to Toolkit to be 1.4 compliant.

2.1. Properties->Java Compiler

  • [x] Enable project specific ...
    • Compliance level [1.4]

You also need to avoid using 1.5/1.6 APIs:

2.2. Right click on JRE System Library in the package explorer

  • Configure...
  • Change JRE System Library to 1.4
    • add if not available (Installed JREs->Add..)

3. Formatting etc

You can set the coding convention (etc) preferences either as a workspace (preferred) or project preference.

3.1. Window->Preferences->Java->Code style->Clean Up

  • Import ITMillToolkitCleanup.xml (source:trunk/eclipse)
  • the result should be named "IT Mill Toolkit Cleanup 20071113"

3.2. Window->Preferences->Java->Code style->Formatter

  • Import ITMillToolkitJavaConventions.xml (source:trunk/eclipse)
  • the result should be named "IT Mill Toolkit Java Conventions 20071114"

3.3. Window->Preferences->Java->Editor->Save Actions

  • [x] Perform the selected actions ...
    • [x] Format
    • [x] Organize imports
    • [x] Additional actions
      • Remove 'this' qualifier for non static field accesses
      • Remove 'this' qualifier for non static method accesses
      • Convert control statement bodies to block
      • Add missing '@Override' annotations
      • Add missing '@Deprecated' annotations
      • Remove unused imports
      • Remove unnecessary casts
      • Remove trailing whitespace on all lines

Discussion

Some of the applied formatting/cleanups, and why:

  • Tab policy Spaces only; not "Mixed" (consistency), not "Tabs only" (not java conventions compatible)
  • Braces around if/for/while blocks: 1) The conventions say so 2) "Always" is a much simpler rule to follow than "if unclear"
  • remove unnecessary "this" (this.variable, this.method()): for consistency; the alternative is always add "this", "this" sometimes not acceptable
  • Disabling "block comment formatting" would solve GWT jsni code indent problem, but we do want to format other block comments. Using "/*-" is a better solution.
  • remove unused imports, remove unnecessary casts: no harm, cleaner code
  • decided against "remove unused [members|variables]", because it might remove stuff while the code is work-in-progress
  • remove trailing whitespace; no harm, cleaner