Difference between revisions of "Coding Conventions"

From Deep Blue Robotics Wiki
Jump to: navigation, search
Line 25: Line 25:
 
}</nowiki>
 
}</nowiki>
  
4. Every non-constructor/non-inherited (or main) method should have a comment that includes any necessary <span style="color:#20AB7E">@params</span> and <span style="color:#20AB7E">@returns</span> on the line above it and every class should have a description at the beginning. Comments should also have a space after the // or /* before the text begins.
+
4. Every non-constructor/non-inherited (or main) method should have a comment that includes any necessary <span style="color:#20AB7E">@params</span> and <span style="color:#20AB7E">@returns</span> on the line above it and every class should have a description at the beginning. Comments should also have a space after the <span style="color:#20AB7E">//</span> or <span style="color:#20AB7E">/*</span> before the text begins.
 
  <nowiki>
 
  <nowiki>
 
/**
 
/**

Revision as of 22:13, 29 September 2016

These are the official coding conventions that we will use when programming in Java. Coding conventions make the code cleaner and easier to read, and should be followed at all times.

1. Class names are capital.

public class ExampleClass {

}

2. Method and variable names are camel-case (thisIsCamelCase), package names are lowercase, and they should all be named appropriately and consistently, and grouped together in a way that makes sense.

package examplepackage;

public class ExampleClass {
    public static void exampleMethod() {
        int exampleInteger = 1;
    }
}

3. Open curly brackets belong on the same line as the statement and one line can only have either one semicolon or one curly bracket (unless it is an if-else statement).

if (bool) {
    bool = false;
} else {
    bool = true;
}

4. Every non-constructor/non-inherited (or main) method should have a comment that includes any necessary @params and @returns on the line above it and every class should have a description at the beginning. Comments should also have a space after the // or /* before the text begins.

/**
 * An example class.
 */
public class ExampleClass {

    /**
     * An example method.
     * @param integer: an example parameter.
     */
    public static void exampleMethod(int integer) {
        int exampleInteger = integer;
    }
}

5. Add an empty line between methods and groups of variables and use spaces between operators (c = a + b) and before curly brackets.

6. No extra spaces not previously specified, unless needed to increase legibility of code.

7. Use of parentheses is encouraged to clarify code, but should not be too excessive

8. You can use Ctrl-Shift-F to auto-format code to follow most of these conventions

Example:

package mypackage;

import SuperClass;
import Interface;

/**
 * This class is an example of how your code should be formatted.
 */
public class Example extends SuperClass implements Interface {

    int variable1 = 42;
    boolean variable2 = false;
    String variable3 = "Hello";

    public static void main(String[] args) {
        if (true) {
            getSum(1, 5);
        } else {
            getDifference(5, 1);
        }
    }

    public Example() {
        super();
         }

    /**
     * Adds two numbers.
     * @param a - An integer that is added to b.
     * @param b - An integer that is added to a.
     * @return The sum of a and b.
            */
    protected int getSum(int a, int b) {
        return a + b;
    }

    /**
     * Subtracts two numbers.
     * @param a - An integer that b is subtracted from.
     * @param b - An integer that is subtracted from a.
     * @return The difference of a and b.
     */
    protected int getDifference(int a, int b) {
        return a - b;
    }
}