Style Guide

A big part of this course is confining to the style guide that the I.B. has set up for us. This is consistent with just about any future CS class that you might take. Every professor, company, team, or learning program will have its own style guide that you have to make sure you conform to. There will be times where your code works perfectly but your style is no good. In those cases, your grades will not be as high as they could be and you’ll most likely be annoyed about it.

So follow this guide as closely as possible!

Here are a few points to remember:

• Consistency: Similar decisions should be made within similar contexts.

• Brevity: Everything should be made as simple as possible, but no simpler. – Albert Einstein

• Clarity: Code should be chosen so as to communicate clearly to the human reader.

• Transparency: Appearance should summarize and reflect structure.

General Formatting

1. No tab characters. You may feel inclined to use tab characters to align text. Do not do so; use spaces instead.
2. 80 or 120 column limit. No line of code should extend beyond 80 characters long. Using more than 80 columns typically causes your code to wrap around to the next line, which is devastating to readability. You may choose to use 120 character limit as most modern IDE’s support that, if you do, please be consistent. Don’t interchange 80 and 120.
3. No needless blank lines. If you are separating methods from each other, only use one line. There should be no blank lines within methods unless there is a clear change in logic.
4. Spacing for operators. Operators (arithmetic operators like + and *, the assignment operator =, etc.) should be surrounded by spaces.

✔ int myNumber = (4 + 5) * 2;
✗ int myNumber = (4+5)*2;

Conditionals and Loops

When writing conditional, make sure that conditional statements are in line with each other. You may choose to use a bracket in the next line, or in the same line as the conditional statement. Above all, choose one and be consistent.

✔ Correct, consistent style:

int num = 10; 

if (num > 5) 
{
    System.out.println("Whoa, big number!"); 
} 
else if (num == 4) 
{
    System.out.println("Whoa, such bad luck number"); 
} 
else 
{
    System.out.println("Whoa, small number"); 
}

✗ Incorrect style, conditional statements are not aligned:

int num = 10; 

if (num > 5) 
{
System.out.println("Whoa, big number!"); 
} else if (num == 4) {

System.out.println("Whoa, such bad luck number"); } else {

System.out.println("Whoa, small number"); }

✘ Inconsistent, and incorrect, style. The curly braces are all in different positions:

int num = 10; 

if (num > 5) 
{
    System.out.println("Whoa, big number!"); 
} 
else if (num == 4) {

    System.out.println("Whoa, such bad luck number"); 
} 
else{

    System.out.println("Whoa, small number"); }

Loops

Loops should follow the same style as conditionals.

✔ Correct, consistent style:

int num = 10; 
while (num < 5) {

    System.out.println("Small numbers!!!");
    count++; 
}

for (int count = 0; count < num; count++) {

    System.out.println("Small numbers!!!"); num--;
}

✘ Please no:

int num = 10; while (num < 5){

    System.out.println("Small numbers!!!"); 
    count++;}

for (int count = 0; count < num; count++) { 
System.out.println("Small 
numbers!!!"); 
num--; 
}

Documentation/Comments

It’s recommended that comments are concise and descriptive. Most comments should only span one line unless you want to explain in depth a solution to a problem. Multi-line comments should be placed directly on top of the method(s) being described.

✔ Correct, consistent style:

//num keeps a running count int num = 10;

for (int count = 0; count < num; count++)
{
    System.out.println("Small numbers!!!"); 
    num--;
}

/* A for loop is used instead of a while loop because it lends itself better to this
 simple problem. A while loop doesn’t not let us keep a count variable to use.*/ 
int num = 10;

for (int count = 0; count < num; count++)
{
    // Prints the necessary message 
    System.out.println("Small numbers!!!"); num--;
}

✘ This just looks strange and it’s inconsistent:

// num is the count 
// that helps the for loop know when 
//to stop int num = 10;

for (int count = 0; count < num; count++)
{
    System.out.println("Small numbers!!!"); 
    num--;
}

Parameters and Naming

Methods should use expressive names and parameter names. One-letter parameter names are not to be used unless it is very clear what they represent. Make sure that brackets and parenthesis align correctly. If the method has many parameters, place them in a line of their own.

✔ Correct, consistent style:

public void sortArray(int[] inputList, 
                      int listSize, 
                      char option,
                      boolean toReverse,
                      Object heuristic ) { 

//implemetation here...

}

✘ Insta-zero:

public void sortArray(int[] l, int s, char opt, boolean r, Object obj) { 

//implemetation here...

}

Instance variables

1. Access modifiers must be consistent. Any fields (instance variables) must be private. There is no excuse to have a public field. If you need to have a static constant, it can be public but you must have a good reason to do so.
2. Fields must be instantiated in the constructor.
3. Helper methods must be private. Public methods should only be those that are available to outside classes.

✔ Correct, consistent style:

private String instanceVariableOne; 
private int instanceVariableTwo;

public static final String CONSTANT_VARIABLE = "Edwin"; 
private final int CONSTANT_TWO = 5;

public Constructor() 
{
    instanceVariableOne = "";
    instanceVariableTwo = 0; 
}

✘ Not consistent:

public String instanceVariable = "";  //should not be public, should be private
public int instanceVariable = 0; //should be instantiated in constructor
private String CONSTANT_VARIABLE = "edwin"; //should also be final and static

Magic Numbers

1. Any magic numbers should be declared as final fields and be named with ALL CAPS.
2. Magic numbers are any numbers that are used directly in your code. There should be none of these as they make code hard to read and really hard to maintain/change.
3. String constants must be final and named in ALL CAPS.

✔ Correct, consistent style, it’s clear what the integers values represent:

private final int MAXIMUM_LENGTH = 5; 
private final int MAX_ASCII_VALUE = 97; 
private final int MIN_ASCII_VALUE = 65;

...

if (char_value < MAX_ASCII_VALUE) 
{ 
    System.out.println(char_value); 
}

✘ It’s not clear what 65 represents, so it’s **magical**:

if (char_value < 65)
{ 
    System.out.println(char_value); 
}