Coding Conventions

As the project is growing, we need a minimal set of guidelines to insure the stability of the MATSim project and its further development. I try to keep this list as short as possible.

We try to follow the Java Code Conventions

This includes the Naming Conventions (Classes start with capital letters, variables with lowercase letters, ...), the usage of braces in if statements and other stuff. A notable exception are line lengths (we have no problem with lines up to 132 characters).

Indentation

MATSim Source code is indented with tabs, not spaces.

Code is consistent and compiles!

Code committed to the repository has to compile - always. If you want to try out some stuff, do it somewhere else or do not commit it. Classes in org.matsim.* do not reference other classes outside of the org.matsim.*-package except for classes provided by libraries in the libs directory. Especially, org.matsim.*-classes must not reference playground-classes. Also playground classes must not depend on code within src/test/java.

Compilation and the compile order is very important for nightly builds, nightly tests and code analysis. Please make sure your code compiles. Also note that Eclipse's compiler settings may be different from the nightly settings. If you are not sure if your code is compiling due to special settings or dependency issues you can check it by calling mvn compile test-compile from the command line within the project top-level directory.

All our code files have the MATSim-specific GPL-Header

In Eclipse, you could add the header to the code template, so every new Java file has this header set by default. To do this, go to the global Preferences in Eclipse (Menu: Window > Preferences), navigate to Java > Code Style > Code Templates. Choose "Code > New Java files" and click on "Edit...". Paste there the following text:

/* *********************************************************************** *
 * project: org.matsim.*
 * ${file_name}
 *                                                                         *
 * *********************************************************************** *
 *                                                                         *
 * copyright       : (C) ${year} by the members listed in the COPYING,        *
 *                   LICENSE and WARRANTY file.                            *
 * email           : info at matsim dot org                                *
 *                                                                         *
 * *********************************************************************** *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *   See also COPYING, LICENSE and WARRANTY file                           *
 *                                                                         *
 * *********************************************************************** */

${filecomment}
${package_declaration}

${typecomment}
${type_declaration}

We use meaningful commit-messages

Commit messages help to rule out quickly some revision of a file when looking for specific changes that, for example, may have introduced a bug in the code. Useless or empty commit messages make it more cumbersome, as the file itself must be looked at in each revision. Additionally, we write commit-messages (as well as comments in the code) in English, as development takes place in many different areas, and not only in german-speaking Countries. KDE has a nice list of SVN Commit Policies, most of them are general enough to also be useful to org.matsim.* ("Never commit code that doesn't compile", "Test your changes before committing", ...)

Do not commit personal test-data

Use another repository if you want to version your personal test-data. We often work with data we are not allowed to give away, as our repository on Sourceforge.net is open for reading to anyone, it is a bad idea to store test-data in this repository, because sooner or later somebody will commit confidental data to the repository which could not be removed! Some simple test-data is available in the directory examples, which is maintained by Michael Balmer and Marcel Rieser – please contact them if you want to add your own examples to this directory.

Naming Conventions

• We follow the Naming Conventions from Sun's Java Code Conventions.
  Short version: Use CamelCase in general, with:
  • Classes and Interfaces starting with uppercase letters
  • Methods, packages and variables/members starting with lowercase letters
  • Constants use all-uppercase letters together with underscores ("_").
• Abbrevations should be avoided:
  • getTravTime()  >>  getTravelTime()
  • getDist()  >>  getDistance()
• Id is an abbreviation for Identifier, the 'd' is thus usually a lowercase letter.
• Factory methods are named create*(), e.g. createLink(). newLink() or other names should be avoided.
• Abstract classes should start with Abstract, e.g. AbstractPersonAlgorithm.
• Interfaces are not specially marked in their name, e.g. there is no pre- or suffix I like SomeInterfaceI.
• Default Implementations of interfaces end on Impl, if no more specific class-name is suitable, e.g. PlanImpl implements Plan.

Committing to the Repository

• Code to be committed must compile.
  Please make a SVN-Update of complete MATSim before committing your own code to make sure your code compiles together with the code currently in the repository. It is important that your code is written in UTF8, otherwise it may not compile on all machines.
• By default, only commit to your personal playground. Do not commit to org.matsim.* unless you are the maintainer of a package/module in org.matsim.*, then you can also commit to this package. Only a small group of persons has the right to commit code to org.matsim.core.*, if you're not one of them, do not commit code in there. Talk to one of the core committers if you need changes or want to contribute code into the core.
• If you commit code to org.matsim.*, run first the test cases before committing and make sure there are no test failures.
• Write useful commit messages.
  If you only commit to your personal playground, a commit message is optional. In all other cases, a commit message is required.
• Write your commit messages in English.
• Do not commit personal data (=non-code) files to the repository.
  Exception is data for test cases, which must be committed to test/input/*. See the detailed discussion of this topic.

KDE has a nice list of additional recommendations for committing code to a repository. The list seems mostly reasonable also for our project, but we don't want to regulate too much, but hope for people's sanity when committing code.

Data on SourceForge-repository

Some questions occurred about committing data to the MATSim project on SourceForge. To clarify, what kind of data is allowed to commit and where to put it, here a short guideline:

1. Only commit source files in "src" and its subdirectories. Do not commit any data files under "src"!
   Exception:
   • MATSim "config.xml" files are allowed under "src/playground/<username>".
2. If you need to use data during the development and you want to keep that data on a save place, please use internal storages of you institution (e.g. internal CVS repositories, internal shared folders, etc.)
3. When you write JUnit test cases under "test/src", you are allowed to add required data to "test/input" or "test/scenario". Then please follow the following constraints:
   • Use—if possible—already existing scenario data sets given in "test/scenario".
   • Add only small data sets (some Kbytes to max. 2 Mbytes) to "test/input" or "test/scenario". Note that bigger files may be compressed with gzip since MATSim supports reading and writing gzipped files with org.matsim.utils.io.IOUtils.getBufferedReader() and IOUtils.getBufferedWriter() respectively.
   • Use artificial or falsified data in test cases and put them under "test/input" or "test/scenario". Remember: SourceForge is public to everyone!

 So, to make it short: You are not allowed to add any data to the SourceForge repository except:

• config.xml-files in your playground
• files required for official JUnit test cases in "test/input/<name of your test>" or "test/scenario/…".

Test Cases

Why Tests?

Our main reason to have tests is to ensure we do not loose existing functionality when adding new functionality. Another reason, hopefully getting less important, is to figure out what influences bugs had, respectively what is influenced by a bugfix.

Possible Examples of Tests

The following list is not complete and likely never will. It is more to give you an idea, what could be tested:

• readers and writers for data (Generating data, writing data to file. Reading the file and writing it out again should produce the same file as before).
• calculating link travel times based on events
• events-generation, e.g. from the transport simulation
• calculation of plans' scores
• are parameters correctly reflected in the execution (e.g. when replanning?)
• ...
  

Automatic Run of the Tests

The tests are automatically run every night. When you log in on matsim.org, you'll find a link in the left navigation area ("developer info") where you can look at the nightly status of the tests. If errors or failures occur, an email is sent to Marcel Rieser who will then inform people as necessary.

More Information

export MAVEN_OPTS=-Xmx600m
mvn test

 public class MyTests extends TestCase {
     protected void setUp() throws Exception {
         super.setUp();
         // your code here...
     }
     protected void tearDown() throws Exception {
         super.tearDown();
         // your code here...
     }
     public final void testOne() {
         // your code here...
         assertEquals(expected, actual);
     }
     public final void testTwo() {
         // your code here...
         assertNotNull(someObject);
     }
 }

 import org.junit.Assert;
 import org.junit.Test;

 public class MyTests {
     @Test
     public final void testOne() {
         // your code here...
         Assert.assertEquals(expectedValue, actualValue);
     }
     @Test
     public final void testTwo() {
         // your code here...
         Assert.assertNotNull(someObject);
     }
     @Test @Ignore("not yet fully implemented")
     public final void testThree() {
         // your code here...
         // TODO complete test
     }
 }

 import org.junit.Assert;
 import org.junit.Rule;
 import org.junit.Test;

 public class MyTests {
     @Rule public MatsimTestUtils utils = new MatsimTestUtils();
     @Test
     public final void testOne() {
         String inputFile = utils.getInputDirectory() + "myFile.txt";
         // your code here...
         String outputFile = utils.getOutputDirectory() + "myFile.txt";
         Assert.assertEquals(expectedValue, actualValue);
     }
 }

Adding a dependency

Introduction

Maven maintains an explicit dependency graph, which code uses which other code in order to compile. If your code requires code from other developers, either from a different playground or in form of an external java library, this dependency must be manually registered in order to keep the code compiling.

Adding another playground as a dependency

Imagine you want to write code that relies on classes in someone else's playground. To do this, you have to specify this dependency on the playground of the other person:

• First make sure you have the playground of the other person loaded in Eclipse (see Creating Eclipse Projects from Maven Modules).
• Open the pom.xml file in your playground
• Switch to the dependencies view (second tab at the bottom of the editor window)
• Click on "Add Dependency"
  
• In the dialog, type in the name of the other playground you want to use
• Select the playground from the list and click ok.
  
• Save the pom.xml.

Adding another library as a dependency

First, make sure the library has a license that is compatible with the GPL that MATSim uses. Gnu.org has an extensive list of compatible and non-compatible licenses. If the license is not compatible, do not use it. Also, do not use SNAPSHOT-versions of libraries as a dependeny. Only use stable versions.

• Open the pom.xml file in your playground
• Switch to the dependencies view (second tab at the bottom of the editor window)
• Click on "Add Dependency"
• In the dialog, type in the name of the other library you want to use
• If the library is available by Maven, it will be listed with the available versions.
• Select the library and the correct version from the list and click ok (Do not select a SNAPSHOT-version!).
• Save the pom file.

Notes

Adding a playground / contrib

Note: The following text will always mention "playground", but the same steps can also be used to create a new contrib-project inside "contribs".

In the playgrounds-project, there exists a directory _template which can be used as a starting point. This template already contains the directory structure and svn meta data for a typical playground. Best is, to copy the template using svn commands. That is:

• on the command line, go to the playgrounds-project: cd /path/to/workspace/playgrounds/
• execute svn copy _template nameOfNewPlayground
• in Eclipse, refresh the playgrounds-project (right-click on project > Refresh, or F5)
• in nameOfNewPlayground/pom.xml, change the Artifact Id and the project name from "_template" to the name of the new playground.
• add the name of the new playground as a module in playgrounds/pom.xml

Core Contributions - Review Process

Contributions to the core of MATSim (packages org.matsim.*) require a high quality and stability. Thus, it is usually not desired to develop now concepts directly in a org.matsim-package, even if the code should later be located there. Instead, contributions to the core should go the following way:

• Draft of the proposed functionality by one or more developers in a playground
• informing MATSim-Core developers of new code, request for comments and reviews
• if the code is considered as finished, inform MATSim-Committee (currently mrieser, mzilske, wrashid) of new code
• MATSim-Committee checks the new code/functionality
• If the code is considered as useful/good by the Committee, the code is moved to org.matsim.core.api.experimental or another appropriate package.
• Usage of the new code at least in the existing core-code. Smaller changes to the new code are still okay in this phase.
• If the new code was proven to be stable/useful in the core, the new code will be moved to org.matsim.api (or other package) on the request of the MATSim Committee.

Documenting your code

Every public class should have the following items:

• For every class, a statement what it is meant for.
• For every class, a very rough description of what it does.
• For every class, the author should be specified with the @author-tag

All these items should be written in a Javadoc block atop of the class.

Eclipse Configuration

MATSim is developed by several persons on different platforms. So we need a basic set of settings to work successfully together.

Text File Encoding

In the Eclipse Preferences, please set the Text File Encoding to "UTF-8", and the New Text File Line Delimiter to "Unix" (in General > Workspace).

Exception Handling

Exceptions are an important concept of Java, as they allow to signal special conditions that need special handling. Java differentiates between two types of Exceptions, checked and unchecked exceptions. Checked exceptions need to be declared in a method and code calling it needs to handle the possible exceptions, for example with a try-catch block:

public void readFile(final String filename) throws IOException {
  // IOException is a checked exception, it needs to be declared as "throws"
  if (!(new File(filename).exists()) {
    throw new IOException("File not found!");
  }
  // continue with normal code if file exists
}

public void doCalculation(final int a, final int b) {
  if (b == 0) {
    // a RuntimeException is an unchecked exception, it does not have to be declared
    throw new RuntimeException("b cannot be zero!");
  }
}

public void someMethod() {
  try {
    readFile("foo.bar");
    // a checked exception must be handled, either with try-catch or by declaring a "throws" on this method
  } catch (IOException e) {
    // handle exception
  }
  doCalculation(3, 0);
}

Java itself makes use of checked exceptions in many places, most notably in many I/O related methods (IOException). As many programmers dislike to handle checked exceptions correctly (to either handle them or declare them and move the handling further up the caller chain), one can often observe code like the following:

try {
  readFile("foo.bar");
} catch (IOException e) {
  e.printStackTrace(); // DO NOT DO IT LIKE THIS!
}

Do not do it like this, as then your code will continue to run as if there was no problem, but you may be missing data in your code, or data was not written out, etc. So you'll spend a lot of time wondering why your application did not do what it should have been.

Better wrap the checked exception in an unchecked exception and re-throw it:

try {
  readFile("foo.bar");
} catch (IOException e) {
  throw new RuntimeException("Could not read the file foo.bar.", e); // This is better
}

In addition, you can still declare the RuntimeException, such that other people using your method know that there could be an exception and optionally handle it:

/**
 * Does some calculation with a and b.
 *
 * @throws RuntimeException if b is zero
 */
public void doCalculation(final int a, final int b) throws RuntimeException {
  if (b == 0) {
    throw new RuntimeException("b cannot be zero!");
  }
  // continue calculation
}

Optionally, you could even create your own (unchecked) Exception:

public class MyCustomException extends RuntimeException {
  public MyCustomException(final String message) {
    super(message);
  }
}

Java-related Information

Most of MATSim-T is written in Java and requires Java 1.5 to run. While Java is widely known, we stumble from time to time over certain features or specialities we'd like to highlight. So this is the place to collect interesting and informative stuff about Java which might (or might not) have some relation to our code.

String.intern();

class Act {
  String type = null;
  ...
  public void setType(String type) {
    this.type = type.intern();
  }
}

 double d = Math.random();

 Random random = new Random();
 random.setSeed(1234);
 ...
 double d = random.nextDouble();

 import org.matsim.core.gbl.MatsimRandom;
 ...
 double d = MatsimRandom.random.nextDouble();

 int baseSeed; // the random seed specified in the configuration file
 ...
 for (int iteration = 0; iteration < 1000; iteration++) {
   MatsimRandom.random.setSeed(baseSeed + iteration);
   ...
 }

MATSim Extensions

Introduction

As a lot of functionality in MATSim is created by PhD students, there is often a problem maintaining this functionality after the respective students finished their work and leave university.  In order to better communicate which features are "standard MATSim" which will (and have to) be maintained by the MATSim core developers, and which features are just "single-developer functionality", MATSim introduces the concept of "MATSim core" and "MATSim extensions".

The core will be maintained by the core developers, and should contain central functionality which is likely to stay in MATSim forever. Extensions can provide new, but stable, functionality developed to solve specific problems which can be of interest to others in the MATSim community.

Extensions will—as long as they compile and pass all tests—also be packaged for releases and be thus optional parts of MATSim releases. This requires that extensions follow certain guidelines, also in order to keep code maintenance and user support in reasonable bounds.

Requirements

• You feel responsible for your extension
• Document the functionality of your extension on the website
• Document the usage of your extension on the website. This documentation should cover topics like (a) How to use it, (b) How to configure it, (c) if it has any special system requirements, (d) optionally have a small tutorial with sample data to demonstrate the functionality.
• If your code offers one or more main classes, make sure to provide useful error message to the user in the case the user submits no or wrong arguments
• If your code offers functionality to other code (e.g. special algorithms and data structures), such classes/interfaces should be well-documented using Javadoc comments.
• You will maintain the code in the case that some updates in MATSim-Core break some functionality in your extension
• You are wiling to assist interested users in the case something is not working as described by your documentation.

Creating your own extension

• Create the code in your playground
• Make sure you meet the code requirements outline above
• Talk to a member of the MATSim committee to request a new contrib-project for your code.
• If the committee agrees to your request, they will create a contrib-project for you, where you can move your code to.
• Write documentation on the website about your extension to comply with the above-mentioned documentation requirements. To do this, add a Child Page to the "Using Extensions" page.
• Once all the code and documentation requirements are met, your extension will be included in future releases and nightly builds will be created for it.

Prefer composition/delegation over inheritance

Inheritance not very robust

There are numerous hints that inheritance is not very stable under refactoring; see, for example, Bloch, "Effective Java".

Use delegation in eclipse

We therefore suggest to prefer composition (=delegation) over inheritance where this is possible.  It is only possible when the class that one wants to inherit from implements an interface.  In that case, the following is possible (with eclipse):

1. Write a class skeleton as follows:

class MyClass implements XXXInterface {
   private XXXInterface delegate = new XXXImplementation(...) ;
}

2. In eclipse, go to "source"/"generate delegate methods" and follow the instructions.

[[Somebody please add a screenshot here. thanks. kai]]

This will delegate all method calls to MyClass to the delegate.  Now you can modify some of the delegate methods as you like.

(This sometimes seems to provide less access than inheritance, but I don't think this is true as long as you assume that internal variables/fields are always private.)

The typical example

It is called "composition" since you can do this with more than one interface/delegate.  The classical example is something like

class MyCar implements HasSteering, HasBrakes, HasGears {
   private HasSteering steeringDelegate = new PowerSteering(...) ;
   private HasBrakes   brakesDelegate   = new SimpleBrakes(...) ;
   private HasGears    gearsDelegate    = new ElectronicGears(...) ;
}

where the eclipse generate delegate methods will produce methods such as

   public void steerToRight( double value ) {
      steeringDelegate.steerToRight( value ) ;
   }
   ...
   public void brake( double value ) {
      brakesDelegate.brake( value ) ;
   }
 

As one can see, this now allows operations such as

   MyCar car ...
   ...
   car.brake( 3. ) ;
   car.steerToRight( 0.3 ) ;
 

that is, the car is now composed of its internals.

Exposing the delegates

In MATSim, we often expose the delegation, that is, the syntax is

  car.getBrakes().brake( 3. ) ;
  car.getSteering().steerToRight( 0.3 ) ;
 

This has the advantage that, if you extend the interfaces, you do not need to adapt every implementation.  It is, clearly, not an option if you want to write a class (such as a PlanStrategy) that is later inserted into the code – that has to fulfill the contract defined by the interface.

Using Generics

Generics can be quite powerful, but also very cumbersome if used wrongly. Thus, respect the following rules:

• Using Generics: that's okay, e.g. when using the Java collection classes
• Providing Generics (i.e. introducing Generics in our own classes): only sparingly if you know exactly what you do. If you are not sure, do not use Generics!