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.
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.
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.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 or written with a Writer 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.
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.
Writing XML documents is pretty straightforward, however a few rules should be followed, so that the files are readable and easily understandable.
<?xml version="1.0" encoding="UTF-8"?><parent><child/></parent><wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:oec="http://ws.openecard.org"
targetNamespace="http://ws.openecard.org"
name="Combined_eCard">
<ShortHand/><ShortHand1/>
<ShortHand2 attr="val" />
<!-- This is the first Group describing XXX -->
<Group1>
<Child/>
</Group1>
<Group1Second/>
<!-- This is the second Group describing YYY -->
<Group2>
<Child/>
</Group2>
<MoreSiblingsOrNot/>
The file structure of any Java file (including enums and interfaces) is as shown below. Some elements are optional.
/****************************************************************************
* 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 <max.mustermann@example.com>
*/
public class Foo extends Bar {
}
Putting these elements together results in the file below. Pay attention to the number of newlines between the elements.
/*
* Copyright (C) 2011 Free eCard Foundation, Inc.
* eCard Public License version 3
*/
⠀
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 <max.mustermann@example.com>
*/
public class Foo extends Bar {
⠀
}
This section deals with the rules specific to Java classes. Most rules are also applicable to Enum and Interface types.
public void setFoo(Foo foo) {
this.foo = foo;
}
public Foo getFoo() {
return this.foo;
}