Open eCard

{{toc}}

h1. Code-Style Guidelines

This document defines style rules and formatting advises, so the resulting code is easily readable and understandable. As this project will be open sourced at some point, the code should reflect the discipline of the team and its work.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

h1. General Rules

h2. Whitespace and Indentation

Almost any editor behaves differently, or at least can, displaying tabs. Automatic code indentation quickly becomes a pain when different settings are chosen for tab-size and indent-size.

The three most frequently used settings are:

# tab-size=4 and indent-size=4

 This setting means that each indentation step is 4 space characters wide and each 4 space indentation block is replaced with a tab character. This setting is very popular so most editors will not need any changes to support it.

# tab-size=8 and indent-size=4

 This setting means that each indentation step is 4 space characters wide and each 8 space indentation block is replaced with a tab character. This is a rather old setting, however it has the advantage that mis-formatting quickly becomes apparent by just looking at the source code.

# no tabs and indent-size=4

 This setting means that each indentation step is 4 space characters wide and tabs are not used at all.

The indentation style in every applicable source file must use the setting tab-size=8 and indent-size=4. There is however one exception. Imported files such as the eCard XML Schema may be reformatted, but it is not required to do so.

h2. Line Endings, Newlines and Line Wrapping

Line endings must be either \r\n for Windows systems and \n for every other system. Git takes care of the proper conversion (see http://stackoverflow.com/questions/3206843/how-line-ending-conversions-work-with-git-core-autocrlf-between-different-operat) only if these characters are used uniformly across a text file. Binary files are not affected by this rule.

One common pitfall is to import XML files containing the wrong or even mixed line endings. Before adding such files to the repository check the line ending and convert it if needed. Sophisticated editors can take care of this task.

Empty lines must only contain the newline character, but no other whitespace characters. Furthermore whitespace between printable characters and the newline character must not be present. Some editors have a feature to indicate these whitespace characters. The formatter should also take care of their removal.

Most newline related rules are explained later in the document.

Regarding text files, the following rule must be applied:

# Add a newline (\n or \r\n on windows) character to the last line containing text

Most of the reasons to do that are historical (see http://stackoverflow.com/questions/729692/why-should-files-end-with-a-newline), however it also has and impact on diffs and the version control system.

Line wrapping rules are relevant, when very wide lines must be wrapped, so they fit on the screen. With todays common widescreen displays, the 80 column rule seems a bit restrictive. But still it is useful to restrict the line site further than the screen can display.

There are a few reasons for that:

# General readability

 It is much harder for the human eye to follow very long lines and jump back to the front on the next line.

 A general rule of thumb is, the longer the line, the more a new line to visually separate the following line of code is needed.

# General comprehensibility

 Long lines tend to carry a lot of information. One line should perform a single action, so that its intention is clear immediately. Command chaining should therefore not be used except there are good reasons to do so.

# Side by Side Display

 When looking at diffs or editing files side by side, the screen size is suddenly only half as wide as it used to be. When the majority of lines is too long, this is practically impossible.

 A line length of 120 columns has proven to be a good value for the line length and thus should not be exceeded in general.

h2. File Encoding

The default file encoding nowadays should be UTF-8. It is often argued that using UTF-16 results in faster text processing. This myth stems from the misconception that UTF-16 is a fixed length encoding, which is not true. In fact only the underlying code table is defined as 2 byte codepage (UCS-2) rather than an 4 byte codepage (UCS-4). Despite its name, UTF-8 is the newer standard.

Besides the UTF file encodings, UNIX systems used to encode in ISO/IEC 8859 or one of its region specific encodings. Windows systems use CP-1252 as default encoding which is an extension to ISO/IEC 8859.

In Java generally everything read with a "Reader":http://docs.oracle.com/javase/6/docs/api/java/io/Reader.html or written with a "Writer":http://docs.oracle.com/javase/6/docs/api/java/io/Writer.html is encoded with the default character set defined by the operating system. That also includes XML processors and serializer. It must be made sure that all data is read accordingly by supplying the respective encoding name to the module.

Source as well as resource files, except binary files, must be encoded as UTF-8. When writing a module which processes text, it must be assumed that the input data is UTF-8 if nothing else is specified like a XML Header or a HTTP encoding header.

h2. Language

It is more than good style to name identifiers in code and write documentation, including comments, in English. There is a high possibility that the code will be read and used by foreign language speakers. Furthermore it gives a uniform picture when only a single language is used.

h1. XML Rules

Writing XML documents is pretty straightforward, however a few rules should be followed, so that the files are readable and easily understandable.

# The file must contain a XML header with newline character

 <pre><code class="xml"><?xml version="1.0" encoding="UTF-8"?></code></pre>

# Indentation of the root element must start at level 0

# Child elements must be one indentation level deeper than their parent element is.

# Child elements may be written inline with their parents only if the parent element's closing tag is also on the same line. The inline use of child elements is not recommended.

 <pre><code class="xml"><parent><child/></parent></code></pre>

# Attributes must be written inline with the element if possible.

 An exception is made when successive attributes exceed the supposed column size. It is then up to the developer to decide whether multiple attributes can be written inline or if each attribute is written on a new line.

# Attributes on new lines must be indented as much as the attribute on the element line.

 <pre><code class="xml"><wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

                  xmlns:oec="http://ws.openecard.org"

                  targetNamespace="http://ws.openecard.org"

                  name="Combined_eCard">

</code></pre>

# Elements without content must be written in shorthand notation (see example).

 <pre><code class="xml"><ShortHand/></code></pre>

# Shorthand notation elements must not include space characters, except one or more attributes are located inside it. In that case there must be exactly one space character.

 <pre><code class="xml"><ShortHand1/>

<ShortHand2 attr="val" />

</code></pre>

# Empty newlines may be introduced into the document to separate groups of elements or single elements which stand out from the context.

 <pre><code class="xml"><!-- This is the first Group describing XXX -->

<Group1>

    <Child/>

</Group1>

<Group1Second/>

<!-- This is the second Group describing YYY -->

<Group2>

    <Child/>

</Group2>

<MoreSiblingsOrNot/>

</code></pre>

h1. Java Rules

h2. File Structure

The file structure of any Java file (including enums and interfaces) is as shown below. Some elements are optional.

# Multiline comment containing the license followed by a newline.

 The license block must have a maximum column width of 80. The first and last line must not contain text. All other lines must be prefixed with the string " * ".

 The Copyright notice should contain the date the file was created and if and edit is done in a different year, then this year. The Copyright holder of the file should also be mentioned.

 <pre><code class="java">/****************************************************************************

 * Copyright (C) 2012-2014 ecsec GmbH.

 * All rights reserved.

 * Contact: ecsec GmbH (info@ecsec.de)

 *

 * This file is part of the Open eCard App.

 *

 * GNU General Public License Usage

 * This file may be used under the terms of the GNU General Public

 * License version 3.0 as published by the Free Software Foundation

 * and appearing in the file LICENSE.GPL included in the packaging of

 * this file. Please review the following information to ensure the

 * GNU General Public License version 3.0 requirements will be met:

 * http://www.gnu.org/copyleft/gpl.html.

 *

 * Other Usage

 * Alternatively, this file may be used in accordance with the terms

 * and conditions contained in a signed written agreement between

 * you and ecsec GmbH.

 *

 ***************************************************************************/

</code></pre>

# Package identifier followed by a newline.

 <pre><code class="java">package org.example.com;

</code></pre>

# Import statements followed by a newline.

 The imports must be sorted lexicographically. They must not include empty lines. Static imports go to the end of the list.

 <pre><code class="java">import java.io.File;

import java.io.Inputstream;

import static org.junit.Assert.*;

</code></pre>

# The class javadoc comment prefixed with a newline and followed by the class definition.

 The class comment must contain an @author tag in the form used in the example.

 <pre><code class="java">

/**

 * Description of class Foo.

 * @see Bar

 * @author Max Mustermann

 */

public class Foo extends Bar {

}

</code></pre>

Putting these elements together results in the file below. Pay attention to the number of newlines between the elements.

<pre><code class="java">

/****************************************************************************

 * Copyright (C) 2012-2014 ecsec GmbH.

 * All rights reserved.

 * Contact: ecsec GmbH (info@ecsec.de)

 *

 * This file is part of the Open eCard App.

 *

 * GNU General Public License Usage

 * This file may be used under the terms of the GNU General Public

 * License version 3.0 as published by the Free Software Foundation

 * and appearing in the file LICENSE.GPL included in the packaging of

 * this file. Please review the following information to ensure the

 * GNU General Public License version 3.0 requirements will be met:

 * http://www.gnu.org/copyleft/gpl.html.

 *

 * Other Usage

 * Alternatively, this file may be used in accordance with the terms

 * and conditions contained in a signed written agreement between

 * you and ecsec GmbH.

 *

 ***************************************************************************/

⠀

package org.example.com;

⠀

import java.io.File;

import java.io.Inputstream;

import static org.junit.Assert.*;

⠀

⠀

/**

 * Description of class Foo.

 * @see Bar

 * @author Max Mustermann

 */

public class Foo extends Bar {

⠀

}

</code></pre>

h2. Java Class

This section deals with the rules specific to Java classes. Most rules are also applicable to Enum and Interface types.

h3. Internal Class Structure

* The class definition must take up exactly one line and must be followed by an empty newline.

 Inner classes are free to disobey the newline rule. However it is advisable to add a newline, if the inner class so big, that it can not be comprehended at once.

The following elements are recommended to appear in the given order, but it is up to the developer to change their ordering and even mix up their elements.

Each block should at least have a newline before and after it, so that is clear that there are different blocks which kind of belong together.

Individual groups can be formed inside these blocks by placing newlines between them. One example may be to separate static and non static members.

* Member variables

* Constructors

* Inner classes

* Functions

 In general functions should be separated by one empty newline.

 When writing functions, the following rules help to create readable code:

** Very short get and set functions can omit the newline.

 <pre><code class="java">

public void setFoo(Foo foo) {

    this.foo = foo;

}

public Foo getFoo() {

    return this.foo;

}

</code></pre>

** Very big functions should be separated by two newlines.

 In case the function is very big (say it takes up the whole screen), then two instead of only one empty newlines can be inserted, so that the reader can quickly find the next function.

** Public Static functions should be separated from non static functions.

 A block of static functions can be placed before the non static functions. Private static functions which are only used in one particular function should be placed directly in front of the using function, so that it becomes apparent that these two functions belong together.

* The end of the class symbol } is prefixed with an empty newline.

 Inner classes are free to disobey the newline rule. However it is advisable to add a newline, if the inner class so big, that it can not be comprehended at once.

 This newline should be in sync with the first newline after the class definition.