Pentaho Platform Java Coding Standards - V1.0

Coding Standards Basis

The Pentaho java coding standards follow the Coding Conventions for the Java Programming Language, published by Sun Microsystems, with local modifications as listed below.

2.2 - Common File Names

3.1.1 - Beginning Comments

Pentaho Open Source software uses the Mozilla Public License. The opening comment should look like this:

/*
 * Copyright 2007 Pentaho Corporation.  All rights reserved.
 * This software was developed by Pentaho Corporation and is provided under the terms
 * of the Mozilla Public License, Version 1.1, or any later version. You may not use
 * this file except in compliance with the license. If you need a copy of the license,
 * please go to http://www.mozilla.org/MPL/MPL-1.1.txt. The Original Code is the Pentaho
 * BI Platform.  The Initial Developer is Pentaho Corporation.
 *
 * Software distributed under the Mozilla Public License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or  implied. Please refer to
 * the license for the specific language governing your rights and limitations.
 *
 * Created
 * @author
 */

4 - Indentation

Two spaces should be used as the unit of indentation. Tab characters must not be used in the source code. Anywhere in the sun document you find references to four spaces for indentation, you should substitute two. When you see eight spaces, please substitute four. The reason for this convention change is for readability.

4.1 - Line Length

Maximum line length: 120 characters.

5.3 (New) - NLS Comments

Pentaho uses the Eclipse convention for commenting lines with embedded strings that should not be flagged by the compiler as non-externalized strings. That convention is as follows:

For each non-externalizable string, there will be an end-of-line comment (//) in the following form:

//$NON-NLS-x$

7.8 - Switch Statements

A switch statement should have the following form:

switch (condition) {
  case ABC: {
    statements;
    // falls through
  }

  case DEF: {
      statements;
      break;
  }

  case XYZ: {
    statements;
    break;
  }

  default: {
    statements;
    break;
  }
}

Every time a case falls through (doesn't include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the // falls through comment.

Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.

The above differs from the sun standard with the addition of the brackets, the falls through comment, and the spacing.

Items not covered by the Sun Guide

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.