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: https://github.com/PalladioSimulator/Palladio-Build-CodingConventions/tree/master/misc/org.palladiosimulator.codeconventions
Configuring Checkstyle in a new IDE
Install the Checkstyle plug-in (http://eclipse-cs.sf.net/update/) 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:
- Check out the plugin "org.palladiosimulator.codeconventions" into your workspace (if not already done)
- Right click on your project; select "Properties"
- Select "Checkstyle"; select tab "Local Check Configurations"
- Select "New..."; Type: "Project Relative Configuration"; Name: "Palladio Coding Conventions"; Location: "/org.palladiosimulator.codeconventions/palladio-checkstyle-rules.xml"
- 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: http://www.eclemma.org/
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 prject site can be found at: https://spotbugs.github.io/
Further information about the plugin and its usage is provided: at https://github.com/spotbugs/spotbugs