Difference between revisions of "Coding Conventions"

From Deep Blue Robotics Wiki
Jump to: navigation, search
 
Line 2: Line 2:
  
 
1. Class names are capital.
 
1. Class names are capital.
  <syntaxhighlight lang="java"><nowiki>
+
  <syntaxhighlight lang="java">
 
public class ExampleClass {
 
public class ExampleClass {
  
}</nowiki></syntaxhighlight>
+
}</syntaxhighlight>
  
 
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.
 
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.
  <nowiki>
+
  <syntaxhighlight lang="java">
 
package examplepackage;
 
package examplepackage;
  
Line 15: Line 15:
 
         int exampleInteger = 1;
 
         int exampleInteger = 1;
 
     }
 
     }
}</nowiki>
+
}</syntaxhighlight>
  
 
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).
 
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).
  <nowiki>
+
  <syntaxhighlight lang="java">
 
if (bool) {
 
if (bool) {
 
     bool = false;
 
     bool = false;
 
} else {
 
} else {
 
     bool = true;
 
     bool = true;
}</nowiki>
+
}</syntaxhighlight>
  
 
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.
 
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>
+
  <syntaxhighlight lang="java">
 
/**
 
/**
 
  * An example class.
 
  * An example class.
Line 39: Line 39:
 
         int exampleInteger = integer;
 
         int exampleInteger = integer;
 
     }
 
     }
}</nowiki>
+
}</syntaxhighlight>
  
 
5. Add an empty line between methods and groups of variables and use spaces between operators  
 
5. Add an empty line between methods and groups of variables and use spaces between operators  
Line 51: Line 51:
  
 
Example:
 
Example:
  <nowiki>
+
  <syntaxhighlight lang="java">
 
package mypackage;
 
package mypackage;
  
Line 97: Line 97:
 
         return a - b;
 
         return a - b;
 
     }
 
     }
}</nowiki>
+
}</syntaxhighlight>

Latest revision as of 22:58, 12 December 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;
    }
}