Project

General

Profile

Style » History » Version 1

Paula Gearon, 01/06/2008 03:46 AM

1 1 Paula Gearon
Coding style in Mulgara has always been intentionally liberal, in order to not stifle the creative process.
2
3
The original style document was developed when the code was being developed commercially, and is no longer available. This guide was built from a consensus of the developers of the day, and hence reflects the preferences of that particular group, who were all co-located together. Mulgara is now a scattered group, with few of the original developers. As such, it is appropriate to rewrite and update the coding standards.
4
5
Note that the only compulsory rules are the ones with MUST or MUST NOT. We strongly advise following rules of SHOULD and SHOULD NOT.
6
7
= General Principles =
8
9
 * In order to facilitate rapid and enjoyable work, each developer should be free to work with a coding style comfortable to them. If an individual has an issue with this style guide, they should bring it to the attention of the group, so that a consensus may be achieved.
10
 * With many individuals practicing their own styles, there are bound to be style conflicts in individual files. In this case the following rules should be followed:
11
  * If you are writing a new file, then you choose the style.
12
  * If you are modifying another's file, then stick to the style of the original file. The exceptions are:
13
   * You are modifying a significant portion of the file (> 10-20%).
14
   * The file is not being actively maintained, and it violates this style guide.
15
16
= Spacing =
17
18
 * All code MUST be written with an indenting of 2 spaces per indent. This allows significant nesting without excessive line wrapping. Look at some of our nested classes and you'll see why we want this rule!
19
 * Each new code block (i.e. code which may be wrapped in {}, except array initializers) MUST have 1 indent. Other indenting (such as method parameters or line breaks) MUST be greater than 1 indent.
20
 * Tab characters MUST NOT be used and MUST be replaced with 2 spaces.
21
 * Spaces SHOULD NOT be consecutive, unless immediately following a newline.
22
 * We are not writing COBOL. You SHOULD NOT align the = character in declarations (this is an explicit example of the rule of consecutive spaces). e.g. You SHOULD NOT write the following:
23
{{{
24
#!java
25
  int a          = 1;
26
  long b         = 2L;
27
  final String c = "hello";
28
}}}
29
  Instead use:
30
{{{
31
#!java
32
  int a = 1;
33
  long b = 2L;
34
  final String c = "hello";
35
}}}
36
 * All commas SHOULD be followed with a single space.
37
 * Casts SHOULD NOT be followed with a space.
38
 * Parentheses () and brackets [] SHOULD NOT have spaces inside of them, except after commas or after a newline. The following are acceptable:
39
{{{
40
#!java
41
  int[] a = new int[] {1, 2, 3, 4};
42
  String b = new String[] {
43
      "Hello",
44
      "there",
45
      "world"
46
  };
47
}}}
48
 * Keywords SHOULD be followed by a space.
49
 * Method calls MUST NOT be followed by a space.
50
 * The . operator MUST NOT be preceded by or followed by spaces, unless splitting a line at that point. An example of acceptable line splitting is:
51
{{{
52
#!java
53
  int result = foo().bar().baz()
54
                   .fizz().fuzz();
55
}}}
56
 * All other binary operators SHOULD have single spaces on either side. This includes:
57
{{{
58
  = == | || && & ^ + - * / %
59
}}}
60
 * The elements of the ternary operator should also have surrounding spaces. e.g.:
61
{{{
62
#!java
63
  return a ? b : c;
64
}}}
65
66
= Vertical Spacing =
67
68
 * There is no fixed point for line wrapping. There are no developers using 80 column terminals, therefor you SHOULD NOT wrap text at, or near, this mark. Conversely, excessive width can also be confusing, so use your judgment here.
69
 * There are two acceptable forms of using braces:
70
  1. Opening braces on the same line as the code commencing the block. Closing braces are either:
71
    * When the current structure has finished, the brace is on a line on its own.
72
    * When followed by more elements, then those elements are on the same line as the closing brace.
73
  1. Opening braces on a new line. Closing braces on a new line. Most Mulgara developers prefer to see the first style to the second, but as this has remained the single most contentious point in programming style for decades, we are allowing the choice.
74
 * Styles MUST NOT be mixed. The following is not allowed:
75
{{{
76
#!java
77
  try {
78
    // some code
79
  }
80
  catch (Exception) {
81
  }
82
}}}
83
 Instead use one of the following:
84
{{{
85
#!java
86
  try {
87
    // some code
88
  } catch (Exception) {
89
  }
90
}}}
91
 or
92
{{{
93
#!java
94
  try
95
  {
96
    // some code
97
  }
98
  catch (Exception)
99
  {
100
  }
101
}}}
102
 Style mixing like this can make a code block appear to have completed when it will actually continue.
103
104
 '' '''NOTE:''' During 2005 someone reformatted many of the source files to violate this. If you are modifying a file that violates this formatting, please consider fixing the formatting as well.''
105
 * Related blocks (if/else and try/catch) MUST NOT be separated by any more newlines than allowable in the chosen style. This means 0 newlines for style 1, and 1 newline for style 2. You MUST NOT do the following:
106
{{{
107
#!java
108
  if (test) {
109
    // code
110
  }
111
  // a comment about the else block
112
  else {
113
  }
114
}}}
115
 This is an exacerbation of the style mixing problem, and is more likely to make a control structure appear to have completed.
116
 * Method bodies MUST have at least one newline between them Method bodies SHOULD be separated by 2 newlines.
117
 * You SHOULD separate logical blocks of code in a single method with a newline.
118
 * Single line code blocks MUST be wrapped in braces if they are on a separate line to the start of the structure. e.g. The braces in the following MUST be used, and are compulsory:
119
{{{
120
#!java
121
  if (test) {
122
    foo();
123
  }
124
}}}
125
 * Single line code blocks MAY appear on the same line as the start of the structure. e.g. The following is permissible:
126
{{{
127
#!java
128
  if (!test) throw new Exception();
129
}}}
130
 '''Note''': This was not allowed in the previous code style.
131
 * No-op blocks MAY place the closing brace on the same line as the opening brace, violating the usual brace style. A comment SHOULD appear with this idiom. e.g.:
132
{{{
133
#!java
134
  try {
135
    file.close();
136
  } catch (IOException e) { /* don't care */ }
137
}}}
138
 * Trivial accessor methods MAY violate the code style by placing all code and braces for the method on a single line, and avoiding line breaks between these methods. This SHOULD NOT occur unless the class is very small and contains almost entirely trivial methods like this. Line breaks MUST NOT be skipped exception between single-line methods. e.g.:
139
{{{
140
#!java
141
  int getX() { return x; }
142
  void setX(int x) { this.x = x; }
143
}}}
144
Note that the last four items were not allowable under the previous style guide. They've been included to permit some useful compression of syntactic salt.
145
146
= Comments =
147
148
 * Classes, methods and members MUST have Javadoc comments. This is our primary documentation for developers, so it is important, even for private methods and members.
149
 * Trivial classes for holding internal values MAY avoid the use of Javadoc on the methods and members, but not on the class. e.g.:
150
{{{
151
#!java
152
  /** Represents a Cartesian coordinate. */
153
  private class Point {
154
    private double x;
155
    private double y;
156
157
  }
158
}}}
159
 * Javadoc for methods MUST describe what the method does. The Javadoc SHOULD describe the usage and purpose of classes, members and methods.
160
 * Good Javadoc on a method can eliminate the need for internal comments. However, anything that is not immediately clear to an experienced programmer SHOULD have an explanatory comment.
161
 * All new code files MUST start with the following file header:
162
{{{
163
#!java
164
  /*
165
   * The contents of this file are subject to the Open Software License
166
   * Version 3.0 (the "License"); you may not use this file except in
167
   * compliance with the License. You may obtain a copy of the License at
168
   * http://www.opensource.org/licenses/osl-3.0.txt
169
   *
170
   * Software distributed under the License is distributed on an "AS IS"
171
   * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
172
   * the License for the specific language governing rights and limitations
173
   * under the License.
174
   */
175
}}}
176
 * Javadoc for the main class in a file MUST include the following tags:
177
{{{
178
#!java
179
  @created
180
  @author
181
  @copyright
182
  @licence
183
}}}
184
 An example is:
185
{{{
186
#!java
187
  /*
188
   * @created 2007-03-23
189
   * @author Paul Gearon
190
   * @copyright &copy; 2007 <a href="mailto:pgearon@users.sourceforge.net">Paul Gearon</a>
191
   * @licence <a href="{@docRoot}/../../LICENCE.txt">Open Software License v3.0</a>
192
   */
193
}}}
194
 The licence MUST be the [http://www.opensource.org/licenses/osl-3.0.php OSL], unless it is based on source from elsewhere, where that source is compatible with the OSL. Compatibility is the developer's responsibility to check, and it MUST be checked carefully. Note that GPL and LGPL code is NOT compatible here!
195
196
In the future, it may be desirable to take portions of any new code and use them in other projects. For this reason, dual licensing using the [http://www.opensource.org/licenses/apache2.0.php Apache License] is encouraged.
197
198
= Code =
199
200
 * Imports SHOULD be listed for each required class. The exception to this is for packages in the Java library where a large number of classes is needed. e.g. If using URLs along with a large number of the collection types, then the following is appropriate:
201
{{{
202
#!java
203
  import java.net.URL;
204
  import java.net.MalformedURLException;
205
  import java.util.*;
206
}}}
207
 * Imports SHOULD be in 3 groups. Groups are separated by a blank line, and may also include a comment describing the group. The groups are:
208
  * java.* packages.
209
  * Mulgara packages.
210
  * Third party packages.
211
 * Compiler warnings SHOULD be avoided. If this cannot be avoided in the code, then use annotations.
212
 * Declarations of a narrowed generic type SHOULD NOT have any extra spaces around or in the type specification. So the following SHOULD NOT be used:
213
{{{
214
#!java
215
  Map <Integer, String> map = new HashMap <Integer, String> ();
216
}}}
217
 Instead, the following style SHOULD be followed:
218
{{{
219
#!java
220
  Map<Integer,String> map = new HashMap<Integer,String>();
221
}}}
222
  Note that this is the only case where commas SHOULD NOT be followed by spaces.