JBoss.orgCommunity Documentation

Chapter 18. Development

18.1. Methodology Overview
18.2. Development guidelines

The diagram below explains the overall structure of the OptaPlanner source code:

In the diagram above, it's important to understand the clear separation between the configuration and runtime classes.

The development philosophy includes:

  1. Fail fast. There are several levels of fail fast, from better to worse:

  2. Exception messages

    1. The Exception message must include the name and state of each relevant variable. For example:

      if (fooSize < 0) {
          throw new IllegalArgumentException("The fooSize (" + fooSize + ") of bar (" + this + ") must be positive.");
      }

      Notice that the output clearly explains what's wrong:

      Exception in thread "main" java.lang.IllegalArgumentException: The fooSize (-5) of bar (myBar) must be positive.
          at ...
    2. Whenever possible, the Exception message must include context.

    3. Whenever the fix is not obvious, the Exception message should include advice. Advice normally starts with the word maybe on a new line:

      Exception in thread "main" java.lang.IllegalStateException: The valueRangeDescriptor (fooRange) is nullable, but not countable (false).
      Maybe the member (getFooRange) should return CountableValueRange.
          at ...

      The word maybe is to indicate that the advice is not guaranteed to be right in all cases.

  3. Generics. The Solution class is often passed as a generic type parameter to subsystems. The PlanningEntity class(es) are rarely passed as a generic type parameter.