Code-style » History » Revision 5
Revision 4 (Johannes Schmölz, 07/04/2012 04:49 PM) → Revision 5/14 (Tobias Wich, 07/23/2012 10:55 PM)
{{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. (not yet defined as license is still
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 " * ".
<pre><code class="java">/*
* Copyright (C) 2011 Free eCard Foundation, Inc.
* eCard Public License version 3
*/
</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.
<pre><code class="java">
/**
* Description of class Foo.
* @see Bar
* @author Max Mustermann <max.mustermann@example.com>
*/
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) 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 {
⠀
}
</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.
h1. Repository Guidelines
The git master repository is available under the following ssh URL:
<pre>git@vserver-001.urospace.de:ecard-client</pre>
The master repository contains the master and stage branch as well as all official tags.
The repository is not writable, except by the integrator.
Every user with git development access has his own repository which is accessible under the following URL:
<pre>git@vserver-001.urospace.de:ecard-client/firstname_lastname</pre>
To get access to your personal repository, you first have to add it to your remotes. This is accomplished by the following command:
<pre> git remote add local-name-for-repo git@vserver-001.urospace.de:ecard-client/firstname_lastname</pre>
local-name-for-repo identifies the remote repository on your local machine. The name can be freely chosen, but it is recommended to use the initials of the developer who owns the repository.
For example, if John Doe wants to add his personal repository to his remotes, he has to execute the following command:
<pre> git remote add jd git@vserver-001.urospace.de:ecard-client/john_doe</pre>
The same command can be used to add repositories of other developers.
h2. Development Workflow
# Set local repository to the commit/branch/tag, where you want to write a feature/fix/...
# Hack
# If you are working on master or stage, or more general when you have to combine your work with any other change, make sure to update your work properly (do a rebase)
# If the change is not a Hotfix, it will most likely go into the stage branch.
# Do a merge request (at the moment at Tobias Wich)
# Check out tests in CI system
# Correct change if needed
# Change goes into master
h2. Commit Rules
Commit messages and the appropriate level of granularity is the essence of a readable and comprehensible history. "Progit sec. 5.2":http://git-scm.com/book/ch5-2.html recommends that commits are revised with @git commit -p@ or @git add -i@ , before being committed.
If however it becomes apparent that the structure of the commits, or its log messages are badly done, a rewrite of the history with @git rebase -i@ can be used. There are other rewrite tools ("magit":http://philjackson.github.com/magit/magit.html#Rewriting) which help with the task at hand. http://alexvollmer.com/posts/2009/01/31/rewriting-history-with-git/ has a nice write-up how to rewrite history with the bundled git commands.
Concerning the commit message, there are a lot of descriptions on the web. Most of them are quite similar. One of the more comprehensive descriptions can be found in "Progit sec. 5.2":http://git-scm.com/book/ch5-2.html in paragraph Commit Guidelines.
A good commit message begins with a header line which is, according to Progit, 50 characters long. I tend to extend this length to ca. 70 characters. We don't live in times where consoles only have 78 character anymore. The header line should contain a brief summary of the changes in the commit. Issue references should go into the body, because nobody knows what is behind them when looking at the log. An exception to this rule is, when the summary is sufficient to describe the change and no body is needed. The summary must use imperative present tense, meaning 'Add X' instead of 'Added X'. The summary ends without a full stop.
If a body is needed, a blank line followed by the body is inserted after the header line. These items are optional, but it is good practise to add them. The line width of the body should be about 100 characters. The body should contain details and perhaps a motivation for the patch. Especially when adding changes in complicated code, think of cryptography for example, the reader may not understand the change without this explanation. The body may consist of several paragraphs which are separated by blank lines.
Enumerations or bullet points can be used inside the body. They should be indented by one space and their text should be aligned by the first character of the items text. Bullet points should be written with *.
<pre>
Short (up to 70 chars) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 100 characters or so. In some
contexts, the first line is treated as the subject of an email and the rest of the text as the body.
The blank line separating the summary from the body is critical (unless you omit the body entirely);
tools like rebase can get confused if you run the two together.
Further paragraphs come after blank lines. Enumerations and bullet points look like this:
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank
lines in between, but conventions vary here
or
1. Point one
2. Another point
</pre>