Mulgara

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

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

h1. Spacing

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

<pre>

<code class="java">

  int a          = 1;

  long b         = 2L;

  final String c = "hello";

</code></pre>

  Instead use:

<pre>

<code class="java">

  int a = 1;

  long b = 2L;

  final String c = "hello";

</code></pre>

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

<pre>

<code class="java">

  int[] a = new int[] {1, 2, 3, 4};

  String b = new String[] {

      "Hello",

      "there",

      "world"

  };

</code></pre>

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

<pre>

<code class="java">

  int result = foo().bar().baz()

                   .fizz().fuzz();

</code></pre>

* All other binary operators SHOULD have single spaces on either side. This includes:

<pre>

  = == | || && & ^ + - * / %

</code></pre>

* The elements of the ternary operator should also have surrounding spaces. e.g.:

<pre>

<code class="java">

  return a ? b : c;

</code></pre>

h1. Vertical Spacing

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

* Braces have one accepted format:

   Opening braces on the same line as the code commencing the block. Closing braces are either:

**** When the current structure has finished, the brace is on a line on its own.

**** When followed by more control structure elements, then those elements are on the same line as the closing brace (example elements are _else_ and _catch_).

   In the past, there was another acceptable style. However, the current developers have now all agreed to the above style.  The previously accepted style had opening and closing braces always on a line on their own.

* A element that continues the current structure MUST NOT be placed on a new line. The following is not allowed:

<pre>

<code class="java">

  try {

    // some code

  }

  catch (Exception) {

  }

</code></pre>

 Instead use the following:

<pre>

<code class="java">

  try {

    // some code

  } catch (Exception) {

  }

</code></pre>

 Starting blocks in a continued control structure like this can make a code structure appear to have completed when it will actually continue.

 _ *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:

<pre>

<code class="java">

  if (test) {

    // code

  }

  // a comment about the else block

  else {

  }

</code></pre>

 This is an exacerbation of the control structure continuation 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:

<pre>

<code class="java">

  if (test) {

    foo();

  }

</code></pre>

* Single line code blocks MAY appear on the same line as the start of the structure. e.g. The following is permissible:

<pre>

<code class="java">

  if (!test) throw new Exception();

</code></pre>

 *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.:

<pre>

<code class="java">

  try {

    file.close();

  } catch (IOException e) { /* don't care */ }

</code></pre>

* 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.:

<pre>

<code class="java">

  int getX() { return x; }

  void setX(int x) { this.x = x; }

</code></pre>

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.

h1. Comments

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

* Trivial classes for holding internal values MAY avoid the use of Javadoc on the methods and members, but not on the class. e.g.:

<pre>

<code class="java">

  /** Represents a Cartesian coordinate. */

  private class Point {

    private double x;

    private double y;

  }

</code></pre>

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

<pre>

<code class="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.

   */

</code></pre>

* Javadoc for the main class in a file MUST include the following tags:

<pre>

<code class="java">

  @created

  @author

  @copyright

  @licence

</code></pre>

 An example is:

<pre>

<code class="java">

  /*

*** @created 2007-03-23

*** @author Paul Gearon

*** @copyright &copy; 2007 <a href="mailto:pgearon@users.sourceforge.net">Paul Gearon</a>

*** @licence <a href="{@docRoot}/../../LICENCE.txt">Open Software License v3.0</a>

   */

</code></pre>

 The licence MUST be the "OSL":http://www.opensource.org/licenses/osl-3.0.php, 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!

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 "Apache License":http://www.opensource.org/licenses/apache2.0.php is encouraged.

h1. Code

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

<pre>

<code class="java">

  import java.net.URL;

  import java.net.MalformedURLException;

  import java.util.*;

</code></pre>

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

<pre>

<code class="java">

  Map <Integer, String> map = new [[HashMap]] <Integer, String> ();

</code></pre>

 Instead, the following style SHOULD be followed:

<pre>

<code class="java">

  Map<Integer,String> map = new [[HashMap]]<Integer,String>();

</code></pre>

  Note that this is the only case where commas SHOULD NOT be followed by spaces.