OpenSHA Coding Standards

Good code is not only well-written, efficient, and well-documented, but also is written with a uniform formatting standard. Below I outline some suggested coding standards we all try to stick with in order to provide a uniform and clean look and feel to our source code files. Please feel free to update this if you feel strongly about a certain topic, these rules are meant to serve as a starting point only.

Many of the configurations recommended below can be set within your IDE of choice.

Syntax

Tabs : Use tabs, not spaces. This allows individuals to adjust indentation to their liking,

Line Length : A single line of code shall not exceed the 80 character printable page width. This rule helps when printing the page, or when viewing the code on a fixed-width terminal.

Line Wrapping : When a single line of code must extend beyond the above 80 character max, the next line should be indented by two (2) tabs (with "tabs" as outlined above).

Code Blocks : Code contained within a containing block shall always be indented by a single tab from the containing block. When creating a new block of code (i.e. functions, loops, if-statements, etc...), the opening bracket "{" shall be on the same line as the start of the block and the closing bracket shall be on its own line aligned to the opening indentation of that block. This is true except for when the code block can fit entirely on a single line, in such a case it is allowable to do so however there should be sufficient space for a leading and trailing space between the code-block body and the brackets. For example:

Good

public void foo () {
    ...
}
public boolean bar () { return true; }

Bad

public void foo ()
    {
...
    }
public boolean bar(){return true;}

Arguments/Parameters? : There shall be a single space character between the method name (or logical controller i.e. "for", "if", "while"), and the opening parenthesis "(", and additional white space between each argument. There shall not be white-space between the argument and its successive separator ("," or ";" etc...) nor shall there be white space between the enclosing parenthesis and its arguments. For example:

Good

public void foo (String str, int k) {
    for (int i = 0; i < 10; ++i) {
        System.out.println(i);
    }
    int j = 10;
    do {
        System.out.println(j--);
    } while (j>0);    
}

Bad

public void foo( String str , int k ) {
    for(int i=0;i<10;++i){
      System.out.println(i);
    }
    int j = 10;
    do{
        System.out.println(j--);
    }while(j>0);
}

Scoping Method/Member? Modifiers : All class members and methods should be fully scoped as applicable. That is, make use of "public"/"protected"/"private", "static", "final" etc... These should go in the order of (for example), public static final String CONST_MEMBER = "Foo";.

Coding for Efficiency

Pre- vs. Post- Increment/Decrement? : When using the pre-/post- increment/decrement operators, one should favor the "pre" form for byte-code efficiency unless the return value is being utilized. Most modern compilers should perform this optimization for you, but why be lazy? Example:

Good

for (int i = 0; i < 10; ++i) {
    ...
}
int j = 0;
while (j < 10) {
    int previous = j++;
    // ... Work with "previous" and "j" ...
    // Where j = previous + 1
}

Bad

for (int i = 0; i < 10; i++) {
    ...
}

Incremental Assignment : Use it. These are the "+=", "-=", "*=", "/=" operators. They can be used on any numerical primitive, and the "+=" can be used on the java.lang.String as well. These have been optimized for efficiency. Example:

Good

int i = 10;
i += 20; // "i" is now 30.

Bad

int i = 10;
i = i + 20; // "i" is now 30.