Programming standards

The OpenTrafficSim core is written in Java 8.

OTS commit checklist

This checklist can be used so see whether code is suitable for committing to the project.

  1. Checkstyle and code formatter
    Have you considered all checkstyle warnings (and solved or knowingly suppressed them), and have you formatted/indented the code (Ctrl+Shift+F in Eclipse) according to the default OTS formatting (see Setting up Eclipse)?
  2. Compiler warnings and error
    Committing code with compiler errors should be avoided at all times. Warnings should be payed attention to.
  3. Override toString()
    For most classes, the toString() method should be overridden. For purposes of debugging and understanding, objects should be able to meaningfully report what they are. In some cases, a superclass may have a sufficient implementation.
  4. Implement serializable
    All classes should implement serializable, accompanied by a private static final long serialVersionUID = #L;, where # is a long formatted as yyyymmdd, e.g. 20171024 for the 24th of October, 2017.
  5. Override equals()?
    The equals method should be implemented for all classes that are probable to be used for equality checks. The default java implementation checks for pointer equivalence, which can in many cases give a wrong result, especially in distributed serialization/deserialization or multiple JVM settings.
  6. Then also override hashCode()
    Whenever an equals() method is defined, a hashCode() method should also be defined, consistently with attributes considered in equals().
  7. Implement Comparable<Class>?
    For classes that are likely to be ordered, the Comparable<Class> interface should be implemented.
  8. Uncaught exceptions in @throws
    All uncaught exceptions that a method may throw, should be documented in the Javadoc under the @throws tag.
  9. Pre- and post-conditions
    In OTS we apply a fail-fast principle. This means that methods should check whether input meets the requirements. For instance, a pointer may not be null, or a value should be positive. For such checks OTS provides several easy and short Throw.when(...) or Throw.whenNull(...) methods.
  10. The above rules also hold for inner-classes

Suggested reading

The OTS Programming standards are very much in line with the book Joshua Bloch - Effective Java. Note that this is a book about java programming practices, and not intended as an introduction to java.

Directory tree structure

ots-core
    src
        main
            java
                org.opentrafficsim.core.packageName
                    ClassFileName.java
            resources
                localepackageName[_XX].properties
        test
            java
                org.opentrafficsim.core.packageName
                    TestClassFileName.java
            resources
                testResourceFileName
   pom.xml

Java Generics

Java Generics are used to prevent accidental assignments of a speed value to a force, the ID of a ship to a container, etc. If at all possible we want the compiler to stop us from writing such assignments. If that really is impossible or creates very slow code, we like to see a runtime exception as early as possible.

Unit Tests

Unit tests ensure that everything is tested at the lowest feasible level. It would waste a lot of time if, during a traffic simulation run, we find that our conversion from miles to kilometers is wrong. Errors like that should be cought earlier and at a much lower level.

Project Reports

The maven site-deploy operation will run all unit tests and create many reports that help to find errors in the JavaDoc comments, shortcomings in the unit tests, code style, duplicate code, etc.

Main Menu

OTS Developers