Home Formatting lines

By placing each statement on a separate line, you make it easier for readers to understand the gist of your code by simply scanning down the left-hand side of your code.

You may feel the compulsion to avoid this rule to, especially when you have short if statements. However, you should avoid doing so. For example, the following is not ok:

if (something) { System.out.println("Ew, a one-liner"); }
if (somethingElse) System.out.println("Even worse");

There may be a few rare cases where it's ok to do the above if it ends up improving readability, but that is something that needs to be decided on a case-to-case basis.

In particular, note that while the code is visually more concise, it is not structurally more concise.

If you feel that combining statements would boost readability, you should talk to a TA first to double-check.

The corrected version looks like this:

if (something) { 
    System.out.println("Hooray for readability!"); 
}
if (somethingElse) {
    System.out.println("I got all my curly braces");
}

The reason why we have these rules is that if your code is too wide, your readers will have to horizontally scroll in order to read your code, which hinders readability.

This is an potential problem, even on large desktop monitors. It's common practice for developers to put multiple windows side-by-side (for example, a web browser open to the left, and their editor to the right). Many tools programmers use are also built around the assumption that the code it inspects is wrapped to a sensible level.

For example, consider the following:

public class LongAndAnnoying {
    public static void main(String[] args) {
        veryAnnoying("hello world",  "blah blah blah", "asdfasdfasdf", 1337);  // We're testing this method by adding in some random characters.
    }

    public static void veryAnnoying(String seedString, String longParamName, String anotherLongName, int finalLongName) {
        // ...
    }
}

The 3rd line and the 5th line would be considered too long – counting the four spaces for indentation at the start, and the comment, we've crossed the 80 character threshold.

We can fix the first long line by moving the comment to the previous line:

public class LongAndAnnoying {
    public static void main(String[] args) {
        // We're testing this method by adding in some random characters.
        veryAnnoying("hello world",  "blah blah blah", "asdfasdfasdf", 1337);
    }

    public static void veryAnnoying(String seedString, String longParamName, String anotherLongName, int finalLongName) {
        System.out.println("foo");
        // ...
    }
}

However, this still leaves us with the long method header. We could try and shorten this by shortening the parameter names, and sometimes that works, but it's a bit of a compromise – we can often do better. In particular, what we can do is wrap our line, like so:

public class LongAndAnnoying {
    public static void main(String[] args) {
        // We're testing this method by adding in some random characters.
        veryAnnoying("hello world",  "blah blah blah", "asdfasdfasdf", 1337);
    }

    public static void veryAnnoying(
                String seedString, String longParamName, 
                String anotherLongName, int finalLongName) {
        System.out.println("foo");
        // ...
    }
}

Note: we don't have any set convention on how you should wrap your lines. The only thing we require is that any wrapped lines such be indented at minimum twice from the the regular indentation level to indicate that they're out of their regular flow.

For example, all of the below would have been acceptable:

public class WrappedLines {
    // ...snip...

    public static void version1(String seedString, String longParamName, 
                                String anotherLongName, int finalLongName) {
        System.out.println("version 1");
        // ...
    }

    public static void version2(String seedString, String longParamName,
                String anotherLongName, int finalLongName) {
        System.out.println("version 2");
        // ...
    }


    public static void version3(
                String seedString, String longParamName,
                String anotherLongName, int finalLongName) {
        System.out.println("version 3");
        // ...
    }

    public static void version4(String seedString, String longParamName,
            String anotherLongName, int finalLongName) {
        System.out.println("version 4");
       // ...
    }
}

Note that the above is not an exhaustive list – there are many, many different valid ways of indenting and wrapping long lines beyond just those three.

However, the following would not be acceptable:

public static void confusing(String seedString, String longParamName,
    String anotherLongName, int finalLongName) {
    System.out.println("confusing");
    // ...
}

The wrapped line is indented only once from the normal flow, so doesn't "stand out" enough – the parameters look as if they were a part of the body of the method which is disorienting to the reader.

You should leave at minimum one blank line between methods for readability:

// My class header comment goes here
public class Example {
    // Method header comment
    public static void main(String[] args) {
        // ...
    }
    
    // method header comment
    public static void method1() {
        // ...
    }
    
    // method header comment
    public static void method2() {
        // ...
    }
}

Omitting blank lines will leave your class feeling cramped and suffocated:

// My class header comment goes here
public class Example {
    // Method header comment
    public static void main(String[] args) {
        // ...
    }
    // method header comment
    public static void method1() {
        // ...
    }   
    // method header comment
    public static void method2() {
        // ...
    }
}

If you want, you can also leave the occasional blank line inside your method to enhance readability.

// My class header comment goes here
public class Example {
    // Method header comment
    public static void main(String[] args) {
        String name = getName();
        int[] data = retrieveData(name);
        data = cleanData(data);
        
        plotData(name, data);
        displayStatistics(data);
    }
    
    // ...snip...
}

That said, don't leave a blank line after every line:

// My class header comment goes here

public class Example {

    // Method header comment

    public static void main(String[] args) {

        String name = getName();

        int[] data = retrieveData(name);

        data = cleanData(data);
        
        plotData(name, data);

        displayStatistics(data);

    }
    
    // ...snip...
}

Do not leave a blank line after an opening curly brace, or before a closing curly brace. It's a waste of space. The indentation and curly brackets are already enough to help us distinguish where a method starts and ends. Think of curly braces like hugs – air hugs where you don't actually touch the person are sort of lame:

// My class header comment goes here
public class Example {

    // Method header comment
    public static void main(String[] args) {
    
        String name = getName();
        int[] data = retrieveData(name);
        data = cleanData(data);
        
        plotData(name, data);
        displayStatistics(data);
        
    }
    
    // ...snip...
    
}

The same principle applies for control flow structures like if statements or for loops – don't do the following:

public class Example{
    // ...snip...
    
    public static void foo(int a, int b) {
    
        if (a < b) {
        
            System.out.println("Foo");
    
        } else {
            
            System.out.println("Baz");
            
        }
        
    }

}

Instead do:

public class Example{
    // ...snip...
    
    public static void foo(int a, int b) {
        if (a < b) {
            System.out.println("Foo");
        } else {
            System.out.println("Baz");
        }
    }
}

Determining how exactly to space out your code can sometimes be difficult. The guiding principle is to try and space your code to maximize readability, but it can sometimes be difficult to tell exactly what is more readable, especially if the difference is just one or two characters.

For example, which of these two method definitions is consider better style?

public static void main(String[] args) {

// or

public static void main( String[] args ) {

Different communities and organizations will have differing opinions as to which version is better. In this particular case, most Java developers will assert that the first version is better, but many PHP developers would disagree and call the second version better.

That said, for the sake of consistency, we do expect you to follow the general Java conventions regarding spacing. While some programming languages and and organizations have different rules, we do expect you to demonstrate that you understand the Java standard.

This means that you MUST leave a space in the following situations:

• Leave a single blank space before every opening curly bracket.

  For example, do if (something) { instead of if (something){. This emphasizes that a control flow condition and its body are two separate units.

• Leave one space between a control flow statement (such as if or for) and its opening paren.

  For example, do if (something) {, not if(something) {. This emphasizes that a control flow statement and its condition are two separate units.

• Leave one space before and after each operator.

  For example, do double bar = 3 + b * (4 - a);, not double bar=3_+b*(4-a);. Give your numbers room to breathe.

  If following this rule causes your expressions to become very long, you should strongly consider breaking your mathematical expression into smaller ones using variables. (This will also let you "name" subexpressions, enhancing readability.)

You should NOT leave a space in the following situations:

• Do not include a space between a method name and its opening paren.

  For example, do public static void test() {, not public static void test () {. This emphasizes that the method name and its arguments are a single unit, unlike control flow statements.

• There should be no space after an opening paren or before a closing paren.

  For example, do double foo = myMethod(a, b, c);, not double foo = myMethod( a , b , c );. This rule exists mostly due to convention – Java programmers will argue those extra spaces adds unnecessary noise.