Project

General

Profile

Code-style » History » Version 8

Detlef Hühnlein, 10/18/2012 06:50 PM

1 1 Tobias Wich
{{toc}}
2
3
h1. Code-Style Guidelines
4
5
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.
6
7
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.
8
9
10
h1. General Rules
11
12
13
h2. Whitespace and Indentation
14
15
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.
16
The three most frequently used settings are:
17
# tab-size=4 and indent-size=4
18
 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.
19
# tab-size=8 and indent-size=4
20
 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.
21
# no tabs and indent-size=4
22
 This setting means that each indentation step is 4 space characters wide and tabs are not used at all.
23
24
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.
25
26
27
h2. Line Endings, Newlines and Line Wrapping
28
29
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.
30
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.
31
32
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.
33
34
Most newline related rules are explained later in the document.
35
Regarding text files, the following rule must be applied:
36
# Add a newline (\n or \r\n on windows) character to the last line containing text
37
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.
38
39
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.
40
There are a few reasons for that:
41
# General readability
42
 It is much harder for the human eye to follow very long lines and jump back to the front on the next line.
43
 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.
44
# General comprehensibility
45
 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.
46
# Side by Side Display
47
 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.
48
 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.
49
50
51
h2. File Encoding
52
53
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.
54
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.
55
56
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.
57
58
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.
59
60
61
h2. Language
62
63
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.
64
65
66
h1. XML Rules
67
68
Writing XML documents is pretty straightforward, however a few rules should be followed, so that the files are readable and easily understandable.
69
70
# The file must contain a XML header with newline character
71
 <pre><code class="xml"><?xml version="1.0" encoding="UTF-8"?></code></pre>
72
# Indentation of the root element must start at level 0
73
# Child elements must be one indentation level deeper than their parent element is.
74
# 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.
75
 <pre><code class="xml"><parent><child/></parent></code></pre>
76
# Attributes must be written inline with the element if possible.
77
 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.
78
# Attributes on new lines must be indented as much as the attribute on the element line.
79
 <pre><code class="xml"><wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
80
                  xmlns:oec="http://ws.openecard.org"
81
                  targetNamespace="http://ws.openecard.org"
82
                  name="Combined_eCard">
83
</code></pre>
84
# Elements without content must be written in shorthand notation (see example).
85
 <pre><code class="xml"><ShortHand/></code></pre>
86
# 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.
87
 <pre><code class="xml"><ShortHand1/>
88
<ShortHand2 attr="val" />
89
</code></pre>
90
# Empty newlines may be introduced into the document to separate groups of elements or single elements which stand out from the context.
91
 <pre><code class="xml"><!-- This is the first Group describing XXX -->
92
<Group1>
93
    <Child/>
94
</Group1>
95
<Group1Second/>
96
<!-- This is the second Group describing YYY -->
97
<Group2>
98
    <Child/>
99
</Group2>
100
<MoreSiblingsOrNot/>
101
</code></pre>
102
103
104
h1. Java Rules
105
106
h2. File Structure
107
108
The file structure of any Java file (including enums and interfaces) is as shown below. Some elements are optional.
109
110
# Multiline comment containing the license followed by a newline. (not yet defined as license is still 
111
 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 " * ".
112
 <pre><code class="java">/*
113
 * Copyright (C) 2011 Free eCard Foundation, Inc.
114
 * eCard Public License version 3
115
 */
116
117
</code></pre>
118
# Package identifier followed by a newline.
119
 <pre><code class="java">package org.example.com;
120
121
</code></pre>
122
# Import statements followed by a newline.
123
 The imports must be sorted lexicographically. They must not include empty lines. Static imports go to the end of the list.
124
 <pre><code class="java">import java.io.File;
125
import java.io.Inputstream;
126
import static org.junit.Assert.*;
127
128
</code></pre>
129
# The class javadoc comment prefixed with a newline and followed by the class definition.
130
 The class comment must contain an @author tag.
131
 <pre><code class="java">
132
133
/**
134
 * Description of class Foo.
135
 * @see Bar
136
 * @author Max Mustermann <max.mustermann@example.com>
137
 */
138
public class Foo extends Bar {
139
140
}
141
</code></pre>
142
143
Putting these elements together results in the file below. Pay attention to the number of newlines between the elements.
144
<pre><code class="java">
145
/*
146
 * Copyright (C) 2011 Free eCard Foundation, Inc.
147
 * eCard Public License version 3
148
 */
149
150
package org.example.com;
151
152
import java.io.File;
153
import java.io.Inputstream;
154
import static org.junit.Assert.*;
155
156
157
/**
158
 * Description of class Foo.
159
 * @see Bar
160
 * @author Max Mustermann <max.mustermann@example.com>
161
 */
162
public class Foo extends Bar {
163
164
}
165
166
</code></pre>
167
168
169
h2. Java Class
170
171
This section deals with the rules specific to Java classes. Most rules are also applicable to Enum and Interface types.
172
173
174
h3. Internal Class Structure
175
176
* The class definition must take up exactly one line and must be followed by an empty newline.
177
 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.
178
179
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.
180
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.
181
Individual groups can be formed inside these blocks by placing newlines between them. One example may be to separate static and non static members.
182
* Member variables
183
* Constructors
184
* Inner classes
185
* Functions
186
 In general functions should be separated by one empty newline.
187
 When writing functions, the following rules help to create readable code:
188
** Very short get and set functions can omit the newline.
189
 <pre><code class="java">
190
public void setFoo(Foo foo) {
191
    this.foo = foo;
192
}
193
public Foo getFoo() {
194
    return this.foo;
195
}
196
</code></pre>
197
** Very big functions should be separated by two newlines.
198
 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.
199
** Public Static functions should be separated from non static functions.
200
 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.
201
202
* The end of the class symbol } is prefixed with an empty newline.
203
 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.
204
 This newline should be in sync with the first newline after the class definition.
205
206 6 Tobias Wich
207
{{include(Logging_guidelines)}}
208
209
210 1 Tobias Wich
h1. Repository Guidelines
211 2 Tobias Wich
212
The git master repository is available under the following ssh URL:
213
<pre>git@vserver-001.urospace.de:ecard-client</pre>
214
The master repository contains the master and stage branch as well as all official tags.
215
The repository is not writable, except by the integrator.
216
217
Every user with git development access has his own repository which is accessible under the following URL:
218
<pre>git@vserver-001.urospace.de:ecard-client/firstname_lastname</pre>
219
220 3 Johannes Schmölz
To get access to your personal repository, you first have to add it to your remotes. This is accomplished by the following command:
221
<pre> git remote add local-name-for-repo git@vserver-001.urospace.de:ecard-client/firstname_lastname</pre>
222 4 Johannes Schmölz
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.
223 3 Johannes Schmölz
224
For example, if John Doe wants to add his personal repository to his remotes, he has to execute the following command:
225
<pre> git remote add jd git@vserver-001.urospace.de:ecard-client/john_doe</pre>
226
227
The same command can be used to add repositories of other developers.
228
229
230 2 Tobias Wich
h2. Development Workflow
231
232
# Set local repository to the commit/branch/tag, where you want to write a feature/fix/...
233
# Hack
234
# 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)
235
# If the change is not a Hotfix, it will most likely go into the stage branch.
236
# Do a merge request (at the moment at Tobias Wich)
237
# Check out tests in CI system
238
# Correct change if needed
239 1 Tobias Wich
# Change goes into master
240 5 Tobias Wich
241
h2. Commit Rules
242
243
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.
244
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.
245
246
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.
247
248
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.
249 1 Tobias Wich
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.
250 7 Tobias Wich
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 -.
251 5 Tobias Wich
252
<pre>
253
Short (up to 70 chars) summary of changes
254
255
More detailed explanatory text, if necessary. Wrap it to about 100 characters or so. In some
256
contexts, the first line is treated as the subject of an email and the rest of the text as the body.
257
The blank line separating the summary from the body is critical (unless you omit the body entirely);
258
tools like rebase can get confused if you run the two together.
259
260
Further paragraphs come after blank lines. Enumerations and bullet points look like this:
261
 - Bullet points are okay, too
262
 - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank
263
   lines in between, but conventions vary here
264
or
265
 1. Point one
266
 2. Another point
267
</pre>