Style Guidelines

While it is important that programs you write function correctly, it is equally important that they be readable and maintainable. This is something that you do not just for yourself, but for others who will be working with or reading the code you write. Coding style guidelines can vary with employer and programming language, but for the purposes of this class we will follow a few simple guidelines.

Indentation

In most programming languages we use indentation to help visualize nested blocks of code. Each level of indentation should be consistent:

DO: Consistent Indentation

int main() {
    for (int x = 0; x < 10; x++) {
        if (x % 2 == 0) {
            printf("%i\n", x);
        }
    }
    return 0;
}

DON’T: Mix different indentation sizes

int main() {
    for (int x = 0; x < 10; x++) {
            if (x % 2 == 0) {
                printf("%i\n", x);
        }
}
return 0;
}

Spacing

To make it easier to read a statement you should have one space between variables, operators, and literals:

DO: Proper spacing inside statements

int main() {
    for (int x = 0; x < 10; x++) {
        if (x % 2 == 0) {
            printf("%i\n", x);
        }
    }
    return 0;
}

Note the spaces after the for and the if. There should only be parenthesis immediately after a function (like the printf). It is not necessary to have spaces between the semicolons (;).

DON’T: Statements with missing spacing

int main() {
    for (int x=0; x<10; x++) {
        if (x%2==0) {
            printf("%i\n", x);
        }
    }
    return 0;
}

DON’T: Use inconsistent spacing

int main() {
    for (int x =0; x< 10; x++) {
        if (x% 2 ==0) {
            printf("%i\n",x);
        }
    }
    return 0;
}

Blocks

Curly braces are used to indicate the start and end of functions, loops, conditional, and blocks.

DO: Start curly braces on the same line a block begins

private void OnTriggerEnter(Collider other) {
    if (other.gameObject.CompareTag("PickUp")) {
        pickupSound.Play();
        ++count;
        SetCountText();
        other.gameObject.SetActive(false);
    }
}

DO: Put a space between the curly brace and any content that preceeds it.

private void OnTriggerEnter(Collider other) {
    if (other.gameObject.CompareTag("PickUp")) {
        pickupSound.Play();
        ++count;
        SetCountText();
        other.gameObject.SetActive(false);
    }
}

Note the spacing between the ending parenthesis and the curly brace at the end of the for and if conditions.

An alternative style that is also acceptable, DO: Start your curly braces on the next line

private void OnTriggerEnter(Collider other)
{
    if (other.gameObject.CompareTag("PickUp"))
    {
        pickupSound.Play();
        ++count;
        SetCountText();
        other.gameObject.SetActive(false);
    }
}

DO NOT: Mix curly brace location styles

private void OnTriggerEnter(Collider other) {
    if (other.gameObject.CompareTag("PickUp"))
    {
        pickupSound.Play();
        ++count;
        SetCountText();
        other.gameObject.SetActive(false);
    }
}

Functions

• Function names must be pascal case: MyFunction
• Function names must reflect the purpose of the function
• Functions should have comments above describing what they do and the inputs and outputs
• Use helper functions with clear utility
  • A helper function is not named “helper”. It is a function that supports another function to provide a given feature/action/data result
  • Better for the organization of code functionality and reduces duplicate code

Comments

• DO NOT comment every single line of code!

  • It makes the code harder to read

• DO comment code that is complex to enhance comprehension

• Functions should have header comments above them explaining:

  • The purpose of the function

  • Paramaters and preconditions (if any)

  • Return data and postconditions (if any)

Here is an example:

/*
    Detects entering a collider set as a trigger and determines the
    correct helper function(s) to call.

    Parameters:
        other - collider the player has hit
 */
private void OnTriggerEnter(Collider other)
{
    if (other.gameObject.CompareTag("PickUp"))
    {
        pickupSound.Play();
        ++count;
        SetCountText();
        other.gameObject.SetActive(false);
    }
}

Variables

• DO NOT USE MAGIC NUMBERS!
  • Make constants hold the values
• Constant names are in all caps and use underscore between words: MY_CONST_VAR
• If you need access to a variable in the Unity inspector and its is NOT needed by other scripts make it a [SerializeField] and NOT public
• Named variables your create should be camel case style: myVar
• Variable names must be descriptive
  • Single-letter variable names are only allowed if it is immediately obvious what they mean. Using i, j, and k as loop variables is common, and some problems have an abstract quantity n or x, but otherwise choose a more descriptive name.
  • Multiple letter abbreviations are ok as long as the meaning is obvious (like col for column) but often writing out the entire word is clearer.
  • Use plural nouns for collections like lists and arrays. If a variable stores a quantity, like the number of letters in a word, do not use letters but instead use letterCount.
  • Clarity is better than brevity. monthyPay is better than monPay or simply pay