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.*
 *                                                                         *
 * *********************************************************************** *
 *                                                                         *
 * 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.