Project

General

Profile

Style » History » Version 2

Paula Gearon, 01/06/2008 04:22 AM

1 2 Paula Gearon
= Style Guide =
2
3 1 Paula Gearon
Coding style in Mulgara has always been intentionally liberal, in order to not stifle the creative process.
4
5
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.
6
7
Note that the only compulsory rules are the ones with MUST or MUST NOT. We strongly advise following rules of SHOULD and SHOULD NOT.
8
9
= General Principles =
10
11
 * 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.
12
 * 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:
13
  * If you are writing a new file, then you choose the style.
14
  * If you are modifying another's file, then stick to the style of the original file. The exceptions are:
15
   * You are modifying a significant portion of the file (> 10-20%).
16
   * The file is not being actively maintained, and it violates this style guide.
17
18
= Spacing =
19
20
 * 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!
21
 * 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.
22
 * Tab characters MUST NOT be used and MUST be replaced with 2 spaces.
23
 * Spaces SHOULD NOT be consecutive, unless immediately following a newline.
24
 * 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:
25
{{{
26
#!java
27
  int a          = 1;
28
  long b         = 2L;
29
  final String c = "hello";
30
}}}
31
  Instead use:
32
{{{
33
#!java
34
  int a = 1;
35
  long b = 2L;
36
  final String c = "hello";
37
}}}
38
 * All commas SHOULD be followed with a single space.
39
 * Casts SHOULD NOT be followed with a space.
40
 * Parentheses () and brackets [] SHOULD NOT have spaces inside of them, except after commas or after a newline. The following are acceptable:
41
{{{
42
#!java
43
  int[] a = new int[] {1, 2, 3, 4};
44
  String b = new String[] {
45
      "Hello",
46
      "there",
47
      "world"
48
  };
49
}}}
50
 * Keywords SHOULD be followed by a space.
51
 * Method calls MUST NOT be followed by a space.
52
 * 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:
53
{{{
54
#!java
55
  int result = foo().bar().baz()
56
                   .fizz().fuzz();
57
}}}
58
 * All other binary operators SHOULD have single spaces on either side. This includes:
59
{{{
60
  = == | || && & ^ + - * / %
61
}}}
62
 * The elements of the ternary operator should also have surrounding spaces. e.g.:
63
{{{
64
#!java
65
  return a ? b : c;
66
}}}
67
68
= Vertical Spacing =
69
70
 * 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.
71
 * There are two acceptable forms of using braces:
72
  1. Opening braces on the same line as the code commencing the block. Closing braces are either:
73
    * When the current structure has finished, the brace is on a line on its own.
74
    * When followed by more elements, then those elements are on the same line as the closing brace.
75
  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.
76
 * Styles MUST NOT be mixed. The following is not allowed:
77
{{{
78
#!java
79
  try {
80
    // some code
81
  }
82
  catch (Exception) {
83
  }
84
}}}
85
 Instead use one of the following:
86
{{{
87
#!java
88
  try {
89
    // some code
90
  } catch (Exception) {
91
  }
92
}}}
93
 or
94
{{{
95
#!java
96
  try
97
  {
98
    // some code
99
  }
100
  catch (Exception)
101
  {
102
  }
103
}}}
104
 Style mixing like this can make a code block appear to have completed when it will actually continue.
105
106
 '' '''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.''
107
 * 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:
108
{{{
109
#!java
110
  if (test) {
111
    // code
112
  }
113
  // a comment about the else block
114
  else {
115
  }
116
}}}
117
 This is an exacerbation of the style mixing problem, and is more likely to make a control structure appear to have completed.
118
 * Method bodies MUST have at least one newline between them Method bodies SHOULD be separated by 2 newlines.
119
 * You SHOULD separate logical blocks of code in a single method with a newline.
120
 * 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:
121
{{{
122
#!java
123
  if (test) {
124
    foo();
125
  }
126
}}}
127
 * Single line code blocks MAY appear on the same line as the start of the structure. e.g. The following is permissible:
128
{{{
129
#!java
130
  if (!test) throw new Exception();
131
}}}
132
 '''Note''': This was not allowed in the previous code style.
133
 * 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.:
134
{{{
135
#!java
136
  try {
137
    file.close();
138
  } catch (IOException e) { /* don't care */ }
139
}}}
140
 * 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.:
141
{{{
142
#!java
143
  int getX() { return x; }
144
  void setX(int x) { this.x = x; }
145
}}}
146
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.
147
148
= Comments =
149
150
 * 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.
151
 * Trivial classes for holding internal values MAY avoid the use of Javadoc on the methods and members, but not on the class. e.g.:
152
{{{
153
#!java
154
  /** Represents a Cartesian coordinate. */
155
  private class Point {
156
    private double x;
157
    private double y;
158
159
  }
160
}}}
161
 * Javadoc for methods MUST describe what the method does. The Javadoc SHOULD describe the usage and purpose of classes, members and methods.
162
 * 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.
163
 * All new code files MUST start with the following file header:
164
{{{
165
#!java
166
  /*
167
   * The contents of this file are subject to the Open Software License
168
   * Version 3.0 (the "License"); you may not use this file except in
169
   * compliance with the License. You may obtain a copy of the License at
170
   * http://www.opensource.org/licenses/osl-3.0.txt
171
   *
172
   * Software distributed under the License is distributed on an "AS IS"
173
   * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
174
   * the License for the specific language governing rights and limitations
175
   * under the License.
176
   */
177
}}}
178
 * Javadoc for the main class in a file MUST include the following tags:
179
{{{
180
#!java
181
  @created
182
  @author
183
  @copyright
184
  @licence
185
}}}
186
 An example is:
187
{{{
188
#!java
189
  /*
190
   * @created 2007-03-23
191
   * @author Paul Gearon
192
   * @copyright &copy; 2007 <a href="mailto:pgearon@users.sourceforge.net">Paul Gearon</a>
193
   * @licence <a href="{@docRoot}/../../LICENCE.txt">Open Software License v3.0</a>
194
   */
195
}}}
196
 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!
197
198
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.
199
200
= Code =
201
202
 * 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:
203
{{{
204
#!java
205
  import java.net.URL;
206
  import java.net.MalformedURLException;
207
  import java.util.*;
208
}}}
209
 * 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:
210
  * java.* packages.
211
  * Mulgara packages.
212
  * Third party packages.
213
 * Compiler warnings SHOULD be avoided. If this cannot be avoided in the code, then use annotations.
214
 * 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:
215
{{{
216
#!java
217
  Map <Integer, String> map = new HashMap <Integer, String> ();
218
}}}
219
 Instead, the following style SHOULD be followed:
220
{{{
221
#!java
222
  Map<Integer,String> map = new HashMap<Integer,String>();
223
}}}
224
  Note that this is the only case where commas SHOULD NOT be followed by spaces.