Java language enumeration types have an ordinal() method that returns the numerical position of each enumeration constant in its class declaration.

According to the Java API [API 2011], Class Enum<E extends Enum<E>> public final int ordinal():

Returns the ordinal of the enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero). Most programmers will have no use for this method. It is designed for use by sophisticated enum-based data structures, such as EnumSet and EnumMap.

The Java Language Specification [JLS 2011] §8.9, "Enums" does not specify the use of ordinal() in programs. However, attaching external significance to the ordinal() value of an enum constant is error prone and should be avoided.

Noncompliant Code Example

This noncompliant code example declares enum Hydrocarbon and uses its ordinal() method to provide the result of the getNumberOfCarbons() method.

enum Hydrocarbon {
  METHANE, ETHANE, PROPANE, BUTANE, PENTANE,
  HEXANE, HEPTANE, OCTANE, NONANE, DECANE;

  public int getNumberOfCarbons() {
    return ordinal() + 1;
  }
}

Although this noncompliant code example works as written, its maintenance is likely to be problematic. If the enum constants were reordered, the getNumberOfCarbon() method would return incorrect values. Furthermore adding an additional BENZENE constant to the model would break the invariant assumed by the getNumberOfCarbon() method; Benzene has 6 carbons, but the ordinal value 6 is already taken by Hexane.

Compliant Solution

In this compliant solution, enum constants are explicitly associated with the corresponding integer values for the number of carbon atoms they contain. Consequently, the getNumberOfCarbon() method no longer uses the ordinal() to discover the number of carbon atoms for each value.  Different enum constants may be associated with the same value, as shown for HEXANE and BENZENE. Furthermore, this solution lacks any dependence on the order of the enumeration; the getNumberOfCarbon() method would continue to work even if the enumeration were to be reordered.

enum Hydrocarbon {
  METHANE(1), ETHANE(2), PROPANE(3), BUTANE(4), PENTANE(5),
  HEXANE(6), BENZENE(6), HEPTANE(7), OCTANE(8), NONANE(9), DECANE(10);

  private final int numberOfCarbons;

  Hydrocarbon(int carbons) { this.numberOfCarbons = carbons; }

  public int getNumberOfCarbons() {
    return numberOfCarbons;
  }
}

Applicability

Use of ordinals to derive integer values reduces the program's maintainability and can lead to errors in the program.

Related Guidelines

ISO/IEC TR 24772:2010: "Enumerator Issues [CCB]"

Bibliography