4. Code Style

Pentaho enforces coding standards and style through the CheckStyle project ( http://checkstyle.sf.net ).

Please refer to the README.md file for instructions on how to use the supplied configurations.

Items not covered by the CheckStyle project

• Abbreviations and acronyms should not be uppercase when used as name.

• exportXmlAsFile(); // NOT: exportXMLAsFile();

  • As you can see by the above example, Xml is preferred to XML because of what happens when it's connected to the next word in the method. This leads to readability issues.

• All names and comments should be in English

  • English is the preferred language for international development.

• Variables with a large scope should have long names, variables with a small scope can have short names

  • Using i, j, k, etc. is fine for scratch variables, but shouldn't be used for class variables.

• Use plurals on names representing a collection of objects

  • int[] values;
  • List points;

• Language abbreviations should be avoided

  • This makes the code less accessible to community members in other countries. Average is comprehensible or can be looked up in an English-French dictionary - but Avg isn't comprehensible to many, and can't be looked up anywhere.
  • computeAverage(); // NOT: compAvg();

• Domain phrases shouldn't be spelled out

  • In contrast to the above rule, domain-specific phrases that are known by their acronym/abbreviation should be kept as abbreviations. Examples:
  • Use: xml, not extensibleMarkupLanguage
  • Use: roi, not returnOnInvestment
  • Use: cpu, not CentralProcessingUnit

• Ignored caught exceptions must be specified as ignored

  • If an exception is ignored, the exception name should be ignored, and it should include a comment.

} catch ( SQLException ignored ) {
   // Ignored because the connection may be closed here
}

• Type conversions should be explicit

  • Don't rely on implicit type conversion - this communicates to the reader that the developer is aware of the type conversion (and that it wasn't accidental).
  • floatValue = (int) intValue; // NOT: floatValue = intValue;
  • Attach array specifiers to the type not the variable
  • char[] a = new char[20]; // NOT: char a[] = new char[20]
  • Class variables should be declared private
  • This prevents variables from being manipulated in ways that break encapsulation. Possible exceptions are for inner classes that are used for structured storage.

• All methods should have access modifiers

• While package-private has its usefulness, it also looks much less intentional than specifying a modifier. Intentional is preferred. In the few instances where package-private is justified, a comment stating intentional use of package-private and why is required. Junit test case access to methods is one example.