Palladio Coding Conventions

Checkstyle

The Palladio project has defined coding conventions to ensure a common style of Java development. These convenstions are not only limited to the Palladio core development but for all tools developed in the context of Palladio and behind.

The coding rules are derived from the SUN coding conventions and resources to support the development according to these rules is provided. For example, checkstlye rules, initiated from the "Sun Checks (Eclipse)" default configuration are provided. Some rules which were deemed too restrictive have been disabled.

The Eclipse project including the resources is available on GitHub

Configuring Checkstyle in a new IDE

Install the Checkstyle plug-in in Eclipse.

Configuring Checkstyle for an Eclipse Project

Each new source project should have checkstyle enabled (context menu on the project, Checkstyle > Activate Checkstyle). Additional warnings are then computed on source code. To configure checkstyle for a source project, do the following:

1. Check out the plugin org.palladiosimulator.codeconventions into your workspace (if not already done)
2. Right click on your project; select "Properties"
3. Select "Checkstyle"; select tab "Local Check Configurations"
4. Select "New..."; Type: "Project Relative Configuration"; Name: "Palladio Coding Conventions"; Location: "/org.palladiosimulator.codeconventions/palladio-checkstyle-rules.xml"
5. Select tab "Main"; select "Palladio Coding Conventions - (Local)" as a check configuration

As a result, a ".checkstyle" file will be created in your project folder, which looks like this:

<?xml version="1.0" encoding="UTF-8"?>
 <fileset-config file-format-version="1.2.0" simple-config="true" sync-formatter="false">
   <local-check-config name="Palladio Coding Conventions" location="/org.palladiosimulator.codeconventions/palladio-checkstyle-rules.xml" type="project" description="">
     <additional-data name="protect-config-file" value="false"/>
   </local-check-config>
   <fileset name="all" enabled="true" check-config-name="Palladio Coding Conventions" local="true">
     <file-match-pattern match-pattern="." include-pattern="true"/>
   </fileset>
 </fileset-config>

Some generated files (such as EMF generated files) do not comply with the rules. For such files, the warnings can be ignored by selecting the package in section "Exclude from checking" in the checkstyle properties on the project, or checkstyle may be deactivated for the whole EMF generated project. Note: These filter rules are used by the checkstyle check of your local IDE. They are not respected by the build server. However, the common checkstyle rules also used by the Palladio build server is configured to ignore code marked at @generated.

Reference: http://robertmarkbramprogrammer.blogspot.com/2007/07/eclipse-checkstyle-for-new-project.html Reference: http://wiki.eclipse.org/MoDisco/CodingConventions

Handle Xtend Generated Files

Java Code generated with xtend typically reside in a directory xtend-gen. Xtend produces optimized java code neither intended to be read nor manually maintained. Projects making use of xtend should use an adapted .checkstyle configuration file excluding this directory from the checkstyle validation.

 <?xml version="1.0" encoding="UTF-8"?>
 <fileset-config file-format-version="1.2.0" simple-config="true" sync-formatter="false">
   <local-check-config name="Palladio Coding Conventions" location="/de.uka.ipd.sdq.codeconventions/palladio-checkstyle-rules.xml" type="project" description="">
     <additional-data name="protect-config-file" value="false"/>
   </local-check-config>
   <fileset name="all" enabled="true" check-config-name="Palladio Coding Conventions" local="true">
     <file-match-pattern match-pattern="." include-pattern="true"/>
   </fileset>
   <filter name="FilesFromPackage" enabled="true">
     <filter-data value="xtend-gen"/>
   </filter>
 </fileset-config>

Eclipse Formatter

A comfortable way to format code according to the coding conventions is to use the Eclipse Java formatter. To execute the formatter within a Java editor, press (CTRL+SHIFT+F) or right click in the editor and select Source -> Format from the context menu.

We provide an according formatter and clean up configurations with the Palladio development plugin on [Github] (https://github.com/PalladioSimulator/Palladio-Build-CodingConventions/tree/master/misc/org.palladiosimulator.codeconventions).

It is recommended to configuer those rules for your whole workspace. To configure this check out the project mentioned above and go to Window -> Preferences. In the new dialog navigate to Java -> Code Style -> Formatter. Click import and select the file palladio-code-formatter.xml from the checked out development project.

To configure the clean up configuration, go to Window -> Preferences. In the new dialog navigate to Java -> Code Style -> Cleanup. Click import and select the file palladio-cleanup-rules.xml from the checked out development project.

Unit Tests

Code must be covered with unit tests. As common, we use JUnit as test infrastructure and are already going with JUnit version 4. The test coverage is checked by our Build Server.

To test your code coverage locally, we recommend the Eclipse Emma integration provided by the ECLEmma plug-in. Eclipse update site: http://update.eclemma.org/

Encoding

To ensure a common file encoding Palladio projects should be set to UTF-8 encosind. Set: Project -> Properties -> Resources -> Text File Encoding to UTF-8.

SpotBugs (Optional)

SpotBugs (the spiritual successor of FindBugs) provide checks for code patterns which represent or might lead to potential bugs in your software. SpotBugs provides an Eclipse plugin to use these capabilities in your IDE. The project site can be found at: https://spotbugs.github.io/ Further information about the plugin and its usage is provided on GitHub.