Coding Conventions

SPLevo uses a customized set of checkstyle rules and java formatter configurations. They are provided in an according project located at:
https://github.com/kopl/SPLevo/tree/master/Releng/org.splevo.releng.codeconventions

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 coding convention project mentioned above.

It is recommended to configuer those rules for your whole workspace. To do so, check out the code convention project and go to Window -> Preferences. In the new dialog navigate to Java -> Code Style -> Formatter. Click import and select the file splevo-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 splevo-cleanup-rules.xml from the checked out development project.

 

Checkstyle

To work with the SPLevo code in Eclipse, you must install checkstyle support in your Eclipse IDE: http://eclipse-cs.sourceforge.net/
In addition, you should configure the java formater and clean up rules provided in this project. This allows you to run the formater and automatically get a formatting that matches the SPLevo checkstyle rules.

To enable a shared checkstyle rule file, we use external checkstyle rule configurations in each project (see: [http://eclipse-cs.sourceforge.net/advanced_team.html | Using checkstyle settings in a team]). To configure this in a project, the .checkstyle file must be placed in the project, and checkstyle must be activates in the .project file.

.checkstyle file

<?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="SPLevo Coding Conventions" location="/org.splevo.releng.codeconventions/splevo-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="SPLevo Coding Conventions" local="true">
    <file-match-pattern match-pattern="." include-pattern="true"/>
  </fileset>
</fileset-config>

.project File

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
  ...
  <buildSpec>
    ...
    <buildCommand>
      <name>net.sf.eclipsecs.core.CheckstyleBuilder</name>
      <arguments></arguments>
    </buildCommand>
  </buildSpec>
  <natures>
    ...
  <nature>net.sf.eclipsecs.core.CheckstyleNature</nature>
  </natures>
</projectDescription>

A reasonable tool to support your daily work with java doc is the eclipse plugin JAutoDoc. It generates good initial java doc comments which you can improve afterwards.

Source Code Header

The code is published under the epl. To show this, the following code header should be added to java files. If you modify an existing file, add yourself to the list of contributors.

/*******************************************************************************
 * Copyright (c) ${year}
 * 
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    CONTRIBUTR_FIRST_AND_LAST_NAME - WORK_DONE (e.g. "initial API and implementation and/or initial documentation")
 *******************************************************************************/

Note ${year} represents the 4-digits year (e.g. 2014) of creation. ${year} is the notation for the year variable used for code templates in Eclipse as described below.

For new files:
Configure this code header for new files in your preferences Java > Code Style > Code Templates.
Configure it for Comments > Files and use ${year} as variable for the year declaration.
This will automatically add the header to each new file.

For existing files:
If you use JAutodoc, you can configure this code template in your preferences Java > JAutodoc > File Header Section > Add File Header
This allows you to insert the header by pressing Strg + Alt + K