Mulgara

= Style Guide =

Coding style in Mulgara has always been intentionally liberal, in order to not stifle the creative process.

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.

Note that the only compulsory rules are the ones with MUST or MUST NOT. We strongly advise following rules of SHOULD and SHOULD NOT.

= General Principles =

• 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.
• 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: * If you are writing a new file, then you choose the style. * If you are modifying another's file, then stick to the style of the original file. The exceptions are: * You are modifying a significant portion of the file (> 10-20%). * The file is not being actively maintained, and it violates this style guide.

= Spacing = {{{
#!java
int a = 1;
long b = 2L;
final String c = "hello";
}}}
Instead use: {{{
#!java
int a = 1;
long b = 2L;
final String c = "hello";
}}} * All commas SHOULD be followed with a single space. * Casts SHOULD NOT be followed with a space. * Parentheses () and brackets [] SHOULD NOT have spaces inside of them, except after commas or after a newline. The following are acceptable: {{{
#!java
int[] a = new int[] {1, 2, 3, 4};
String b = new String[] {
"Hello",
"there",
"world"
};
}}} * Keywords SHOULD be followed by a space. * Method calls MUST NOT be followed by a space. * 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: {{{
#!java
int result = foo().bar().baz()
.fizz().fuzz();
}}} * All other binary operators SHOULD have single spaces on either side. This includes: {{{ = == | || && & ^ + - * / %
}}} * The elements of the ternary operator should also have surrounding spaces. e.g.: {{{
#!java
return a ? b : c;
}}}

• 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!
• 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.
• Tab characters MUST NOT be used and MUST be replaced with 2 spaces.
• Spaces SHOULD NOT be consecutive, unless immediately following a newline.
• 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:

= Vertical Spacing = {{{
#!java
try {
// some code
}
catch (Exception) {
}
}}}
Instead use one of the following: {{{
#!java
try {
// some code
} catch (Exception) {
}
}}}
or {{{
#!java
try {
// some code
}
catch (Exception) {
}
}}}
Style mixing like this can make a code block appear to have completed when it will actually continue. {{{
#!java
if (test) {
// code
}
// a comment about the else block
else {
}
}}}
This is an exacerbation of the style mixing problem, and is more likely to make a control structure appear to have completed. * Method bodies MUST have at least one newline between them Method bodies SHOULD be separated by 2 newlines. * You SHOULD separate logical blocks of code in a single method with a newline. * 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: {{{
#!java
if (test) {
foo();
}
}}} * Single line code blocks MAY appear on the same line as the start of the structure. e.g. The following is permissible: {{{
#!java
if (!test) throw new Exception();
}}}
'''Note''': This was not allowed in the previous code style. * 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.: {{{
#!java
try {
file.close();
} catch (IOException e) { /* don't care */ }
}}} * 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.: {{{
#!java
int getX() { return x; }
void setX(int x) { this.x = x; }
}}}
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.

'' '''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.''

• 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:

= Comments = {{{
#!java
/** Represents a Cartesian coordinate. */
private class Point {
private double x;
private double y; {{{
#!java
/* * The contents of this file are subject to the Open Software License * Version 3.0 (the "License"); you may not use this file except in * compliance with the License. You may obtain a copy of the License at * http://www.opensource.org/licenses/osl-3.0.txt * * Software distributed under the License is distributed on an "AS IS" * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See * the License for the specific language governing rights and limitations * under the License.
*/
}}} * Javadoc for the main class in a file MUST include the following tags: {{{
#!java
@created
@author
@copyright
@licence
}}}
An example is: {{{
#!java
/* * @created 2007-03-23 * @author Paul Gearon * @copyright © 2007 <a href="mailto:pgearon@users.sourceforge.net">Paul Gearon</a> * @licence <a href="{@docRoot}/../../LICENCE.txt">Open Software License v3.0</a>
*/
}}}
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!

}
}}}

• Javadoc for methods MUST describe what the method does. The Javadoc SHOULD describe the usage and purpose of classes, members and methods.
• 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.
• All new code files MUST start with the following file header:

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.

= Code = {{{
#!java
import java.net.URL;
import java.net.MalformedURLException;
import java.util.*;
}}} * 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: * java.* packages. * Mulgara packages. * Third party packages. * Compiler warnings SHOULD be avoided. If this cannot be avoided in the code, then use annotations. * 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: {{{
#!java
Map <Integer, String> map = new HashMap <Integer, String> ();
}}}
Instead, the following style SHOULD be followed: {{{
#!java
Map<Integer,String> map = new HashMap<Integer,String>();
}}}
Note that this is the only case where commas SHOULD NOT be followed by spaces.

• 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: