Fusor Style Guide

fusor_style_guide.md

Fusor Control Style Guide

This style guide is an attempt to standardize the style used in Fusor Control. This applies to the Java (.java) files and the Arduino (.ino) files. If something is only for Java, it has been noted.

Headers

Yes, I'm aware that the JavaDoc syntax is designed for Java, not Arduino. However, comments in JavaDoc format should be in both Java and Arduino source code files.

Each Java or Arduino source code file should have a file header that includes the author, the date last modified, and the purpose of the file. This should be before any import or package statements in Java, and should be before any #includes in Arduino.

Example (Java):

/**
 * @author John Doe
 * @date 7/23/2021
 * This file is to demonstrate how to use the style guide correctly
 */

Indentation

Code inside (a) methods/functions, (b) classes (Java only), (c) conditionals (d) loops should be indented exactly four spaces.

class StyleDemo {
    int add(int a, int b) {
        int sum = a + b;
        return sum;
    }
    boolean canEnter(int age) {
        if(age >= 18) {
            return true;
        } else {
            return false;
        }
    }
}

Statements

There should be no more than one statement per line.

Incorrect:

int add(int a, int b) {
    int sum = a + b; return sum;
}

Correct:

int add(int a, int b) {
    int sum = a + b;
    return sum;
}

Methods, loops, and if statements

Braces and single-line statements

The header of a method, or the start of a loop or if statement should be immediately proceeded by a space, and then an opening curly brace. There should not be any other statements on the same line as a method, even if there is only one line of code in a method.

Opening curly braces should be on the same line as the start of the loop/method/if statement. Closing curly braces should be on a line by themselves.

Correct:

int add(int a, int b) {
    return a + b;
}

Incorrect:

int add(int a, int b) { return a + b; }

Also incorrect:

int add(int a, int b)
{
    return a + b;
}

Braces

Curly braces are required, even when the statement is only one line. Incorrect:

int add(int a, int b)
    return a + b;

Correct:

int add(int a, int b) {
    return a + b;
}

Operators

All arithmetic (+, -, etc.), assignment (=), relational (==, !=, <, etc.), bitwise (>>, <<, etc.) and logical (||, &&, etc.)* operators should have a space on either side of them. Correct:

int demo = 7;

Incorrect:

int demo=7;

*Logical not (!) is the exception to this. It should have no space following it, and a space before it only if the statement it is inside of should have one.

Loop and condition spacing

For all loops and conditionals (for, while, if), the condition should be preceded by a single space, and also procdeded by a single space, followed by an opening curly brace. In a for loop, there should be exactly one space between the initialization, the condition, and the update.

For a do ... while loop, there should be one space following the do, followed by a single open curly brace. At the end of the loop, there should be a single closing curly brace, followed by one space, followed by while, followed by one more space, followed by the condition, and a semicolon.

Correct:

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

Also correct:

do {
    ...
} while ();

Incorrect:

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

Capitalization

Constant variables (a.k.a. public static final) should be in screaming snake case (e.g. MY_AWESOME_CONSTANT). In Arduino, constants can be denoted by #define, and should be in SCREAMING_SNAKE_CASE, e.g., #define MY_AWESOME_CONSTANT 7.

Local variables should be in camel case (e.g. myAwesomeVariable, i, or test).

The iteration variable in a for loop should be named i. For nested for loops, start with i, then j, then k, etc..

Classes should be in pascal case (e.g. MyAwesomeDemo or Demo).

Misc

No line should be longer than 80 characters (including whitespace).

Method paramaters, variable names, class names, etc. should be descriptive.

Correct:

boolean canEnter(int age) {
    if(age >= 18) {
        return true;
    } else {
        return false;
    }
}

Incorrect:

boolean a(int n) {
    if(n >= 18) {
        return true;
    } else {
        return false;
    }
}

Ternary operator

For those that don't know what it is, it works like this (condition) ? ifConditionTrue : ifConditionFalse. It can be confusing, but is also shorter and [can be] easier to understand for short bits of code.

Never nest termary operators. Ever. I do not want a ternary operator inside another ternary operator. Use an if statement instead.

The condition should be in parenthasis. I'm aware that operator precednce means it isn't strictly required, but it makes the code far easier to read. There should be a space before and after the ?. There should also be a space before and after the :.

When in doubt, don't use it. It is fine to use it properly, as shown below. But, much like goto in C, it also can make code a giant mess. So, use it when it makes sense to. Generally, when you are considering using it, consider this: "Will using the ternary operator make my code harder to read?".

Correct:

boolean canEnter(int age) {
    return (age >= 18) ? true : false;
}

Incorrect:

boolean canEnter(int age) {
    return age>=18?true:false;
}