Java Code Conventions (Style guide)

What is a "Style guide"?

Why have code conventions

• 80% of the lifetime cost of a piece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.

• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
• A style guide makes you a more productive programmer because it reduces gratuitous choice (meningslösa val). If you don't have to make choices about trivial matters, you can spend your energy on the solution of real problems.

It is important to have a reasonable indentation style and to use it consistently in your assignments!
For the conventions to work, every person writing software must conform to the code conventions. Everyone.

If you already have programming experience, in Java or another language, you may be initially uncomfortable at giving up some fond habits. However, it is a sign of professionalism to set aside personal preferences in minor matters and to compromise for the benefit of your group.

Acknowledgments

Adapted with permission from JAVA CODE CONVENTIONS. Copyright 1995-1999 Sun Microsysytems, Inc. All rights reserved. The Java Code Conventions Web site is at: http://java.sun.com/docs/codeconv/

Indentation

General

If I try to formulate a simple "rule" for how to indent it would be (perhaps I have forgotten some more special cases)
A '{' always cause a new line and indentation on the next line e.g.

if (...) {
    xxxxxxx

if (...) {
    xxxxx
}   
nnnnnn

if (...) {
    xxxxx
} else if (...) {
    xxxxx
}

Avoid lines longer than 80-100 characters, since they're not handled well by many terminals and tools and long lines are hard to read.

The first style below is usually better because it saves space. If you desperately want more space use the second style. (The only difference is the placement of the starting block parenthesis({). Sun recomends the first alternative.

class Syntax {
    public static void main( String args[] ) {
        int aVariable = 5;                           // usually declare all variables at top
        if ( aVariable < 6 ) {                       // always use a block ({})
            System.out.println( "True" ) ;
        } else {
            System.out.println( "False" ) ;
        }
    }
}
// ************* second, not so god, style
class Syntax 
{
    public static void main( String args[] ) 
    {
        int aVariable = 5;
        if ( aVariable < 6 ) 
        { 
            System.out.println( "True" ) ;
        } else
        {
            System.out.println( "False" ) ;
        }
    }
}

Always use blockstatements!

if (door.isOpen()) {
    if (resident.isVisible()) {
        resident.greet("Hello!");
    }
} else {
    door.bell.ring();
}	

This is one reason for blockstatements: As in C and C++, the if statement of the Java programming language suffers from the so-called "dangling else problem," illustrated by this misleadingly formatted example:

// DANGEROUS EXAMPLE
if (door.isOpen())
    if (resident.isVisible())
        resident.greet("Hello!");
else door.bell.ring();	// A "dangling else"

Another reason is that a very common bug is to add another statement witout adding a block (if there are no block to start with).

Wrapping Lines

• Break after a comma.
• Break before an operator.
• Prefer higher-level breaks to lower-level breaks.
• Align the new line with the beginning of the expression at the same level on the previous line.
• If the above rules lead to confusing code or to code that's squished up against the right margin, just indent 8 spaces instead.

Examples:

someMethod(longExpression1, longExpression2, longExpression3, 
        longExpression4, longExpression5);
 
var = someMethod1(longExpression1,
                someMethod2(longExpression2,
                        longExpression3)); 

longName1 = longName2 * (longName3 + longName4 - longName5)
           + 4 * longname6; // PREFER

longName1 = longName2 * (longName3 + longName4
                       - longName5) + 4 * longname6; // AVOID 

Following are two examples of indenting method declarations. The first is the conventional case. The second would shift the second and third lines to the far right if it used conventional indentation, so instead it indents only 8 spaces.

//CONVENTIONAL INDENTATION
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
           Object andStillAnother) {
    ...
}

//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother) {
    ...
}

//DON'T USE THIS INDENTATION
if ((condition1 && condition2)
    || (condition3 && condition4)
    ||!(condition5 && condition6)) { //BAD WRAPS
    doSomethingAboutIt();            //MAKE THIS LINE EASY TO MISS
} 

//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
} 

//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
} 

Indentation rules for the usual statements

Simple Statements

argv++;       // Correct
argc--;       // Correct  
argv++; argc--;       // AVOID!

Compound Statements

Compound statements are statements that contain lists of statements enclosed in braces "{ statements }". See the following sections for examples.

• The enclosed statements should be indented one more level than the compound statement.
• The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.
• Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.

Selection

Every time a case falls through (ie. doesn't include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment.

Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.

Example: if statement and it's indentation (always use a block ”{ }”):

if (a<6) {
    System.out.println("a är mindre");
} else if (a==6) {
     System.out.println("a är lika med");   
} else {
    System.out.println("a är större");
}

if (bool-expr) {
    return true;
} else {
     return false;   
}

return bool-expr;

Loops

Example, loop statemenst and their indentation (always use a block ”{ }”):

for (int counter=1; counter<10; counter=counter+1) {
    sum=sum+counter;
}
counter=1;
while (counter<10) {
    sum=sum+1;
    counter=counter+1;
}

• If you know the start and endpoints of the intervall - use for. If you don't know start and/or endpoints of the intervall or you need to stop in the middle - use while.
• The while loop is always executed 0 or more times (this is usually what you need), the do-while is always executed 1 or more times (seldom what you need).

• Since the for-statement is constructed for the above purpose, if you use it in other ways the for-statement would loose its documenting value. Even worse, if not careful the reader may make false assumptions of the semantics of your code based on the standard use of for-statements.
• The for-statement, since it is made up of so many parts, makes it easy to write code that is hard to read and understand.

// do something with every integer i in [l..u] in order 
for(int i = l; i<=u; i++) {
    ... // do something with i
}

// do something with every integer i in [l..u] in reversed order
for(int i = u; i>=l; i--) {
    ... // do something with i
}

// do something with every integer i in [l,l+n,l+2*n,..u]
for(int i = l; i<=u; i = i+n){
    ... // do something with i
}

WARNING! Do not copy this bad example.

// do something with every double d in [0.0, 0.1, 0.2,..,1.0]
for(double d = 0.0; d<=1.0; d = d+0.1){
    ... // do something with d
}

This is because a floating-point number is just an approximation of a real number, and almost every time you make a floating-point arithmetic operation you loose a little more precision. In the example above we keep on making floating-point additions to d and for every operation d becomes more imprecise. However, integer operations in programming languages, if within the bounds of the used integer type, are always exact. Hence, if we rewrite the code above as follows even the last d that we do something with is only subject to one floating-point operation, instead of nine.

// do something with every double d in [0.0, 0.1, 0.2,..,1.0]
for(int i=0; i<=10; i++){
    double d = 0.1*i;
    ... // do something with d
}

There are similar ways to construct most useful series of floating-point numbers.

try-catch Statements

try {
    statements;
} catch (ExceptionClass e) {
    statements;
}

A try-catch statement may also be followed by finally, which executes regardless of whether or not the try block has completed successfully.

try {
    statements;
} catch (ExceptionClass e) {
    statements;
} finally {
    statements;
}

Expressions

if(a==B&&c==d||m==4) ...


if(a==B && c==d || m==4) ...


if(a == B && c == d || m == 4) ...

moms = 25.0;

Identifiers

Variables should be named according to the following rules.

• Avoid abbreviations in names!!!
  (Names should be descriptive ( betecknande på svenska), i.e. they should describe what they represent. The variables year, month and day should be named year, month, day (or år, månad, dag if you are willing to take the chance that swedish characters work) but not for example y, m, d.)
• Varables should be declared at the beginning of a block. See also (LÄNK)
• You should always initialize your variables explicitly and don't count on the automatic initialization.
• Avoid unneccesary variables. See also (LÄNK)

Constants

if (p.getX() < 300) // Don't

	
final double WINDOW_WIDTH = 300;
. . .
if (p.getX() < WINDOW_WIDTH) // OK

Declarations

One Per Line

    int level; // indentation level
    int size;  // size of table

is preferred over

    int level, size;

Do not put different types on the same line. Example:

    int foo,  fooarray[]; //WRONG!

Note: The examples above use one space between the type and the identifier. Another acceptable alternative is to use tabs, e.g.:

int      level;         // indentation level
int      size;          // size of table
Object   currentEntry;  // currently selected table entry

Initialization

Placement

void myMethod() {
    int int1 = 0;         // beginning of method block

    if (condition) {
        int int2 = 0;     // beginning of "if" block
        ...
    }
}

The one exception to the rule is indexes of for loops, which in Java can be declared in the for statement:

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

Avoid local declarations that hide declarations at higher levels. For example, do not declare the same variable name in an inner block:

int count;
...
myMethod() {
    if (condition) {
        int count = 0;     // AVOID!
        ...
    }
    ...
}

Class and Interface Declarations

When coding Java classes and interfaces, the following formatting rules should be followed:

• Methods are separated by a blank line
• No space between a method name and the parenthesis "(" starting its parameter list
• Open brace "{" appears at the end of the same line as the declaration statement
• Closing brace "}" starts a line by itself indented to match its corresponding opening statement, except when it is a null statement the "}" should appear immediately after the "{"

class Sample extends Object {
    int ivar1;
    int ivar2;

    Sample(int i, int j) {
        ivar1 = i;
        ivar2 = j;
    }

    int emptyMethod() {}

    ...
}

Comments

Implementation comments are meant for commenting out code or for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective. to be read by developers who might not necessarily have the source code at hand.

Comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Comments should contain only information that is relevant to reading and understanding the program. For example, information about how the corresponding package is built or in what directory it resides should not be included as a comment.

Discussion of nontrivial or nonobvious design decisions is appropriate, but avoid duplicating information that is present in (and clear from) the code. It is too easy for redundant comments to get out of date. In general, avoid any comments that are likely to get out of date as the code evolves.

Note:The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer.

White space

Blank Spaces

• A keyword followed by a parenthesis should be separated by a space. Example:

         
  while (true) {
             ...
         }
  

  Note that a blank space should not be used between a method name and its opening parenthesis. This helps to distinguish keywords from method calls.

• A blank space should appear after commas in argument lists.

• All binary operators except . should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment ("++"), and decrement ("--") from their operands. Example:

    a += c + d;
    a = (a + b) / (c * d);
    
    while (d++ = s++) {
        n++;
    }
    printSize("size is " + foo + "\n");

• The expressions in a for statement should be separated by blank spaces. Example:

    for (expr1; expr2; expr3)

• Casts should be followed by a blank space. Examples:

    myMethod((byte) aNum, (int) x);
    myMethod((int) (cp + 5), ((int) (i + 3)) + 1);

Blank Lines

Blank lines improve readability by setting off sections of code that are logically related.

One blank line should always be used in the following circumstances:

• Between methods
• Between the local variables in a method and its first statement
• Between logical sections inside a method to improve readability

• Between sections of a source file
• Between class and interface definitions

Methods

• Should do ONE thing well.
• A method should handle all correctly typed arguments.
  Make sure you handle zero and negative numbers, and the empty string.
• Methods should be independent of their "surroundings" and therefore easy to move to another class/main program. Eg. all communication between the method and the caller should happen through parameters and the method must never access global variables.
• A method should normally be short enought to be readable on one screen without scrolling.
• Use a funktion if you can, a procedure if you must.

Programs

Table Of Content: Java^TM Code Conventions (Style guide)

What Is a "style guide"?

Why Have Code Conventions Acknowledgments

Indentation

General

Always use blockstatements!

Wrapping Lines

Indentation rules for the usual statements

Simple Statements

Compound Statements

Selection

Loops

try-catch Statements

Expessions

Identifiers

Constants

Declarations

One Per Line

Initialization

Placement

Class and Interface Declarations

Comments

White space

Blank Spaces

Blank Lines

Methods

Programs