Coding Style

Just like when writing in English, using good style when writing in a programming language is important because it helps you and other people read your code. Easily-readable code is important for you so you can maintain it (update it later), and for other people so they can figure out what it does as easily as possible, and possibly change it. In this class, when writing in Java, you should follow these coding style guidelines:

General style

• Use good modular design. Think carefully about the functions and data structures (variables) that you are creating before you start writing code.
• The main function should not contain low-level details. In other words, the main function should be a high-level overview of your solution, with the low-level details hidden in functions. This is the idea of abstraction.
• As a general guide, no function should be longer than a page of code. There are exceptions, of course, but these should truly be for exceptional cases.
• Use good error detection and handling. Always check return values from functions and handle errors appropriately.
• Try to keep the length of each line manageable. A single Java statement can be split over multiple lines anywhere where a space would be allowed. Unlike Python, no extra syntax (like a backslash) is necessary.

Comments

Use comments frequently throughout your code, especially to explain any complex, tricky, or easily misunderstood sections.

Indentation and curly braces

• Java does not force you to indent your code, but it drastically improves readability.
• By default, the body of any if/else statement, loop, or function, should be indented the same number of spaces or tabs. This ensures that the lines of code that form the body can be easily distinguished from the rest of your program.
• Use a consistent curly brace style. You may choose to have an opening curly brace on the same line of code as the if/else test or function definition, or on a line by itself immediately following. The closing curly brace should be on a line by itself (with a few exceptions).
• You should pick an indentation style, and a style of using curly braces, and stick with it consistently within a single program.

• Two common indentation styles are:

  K & R style:

while (x == y) {
    something();
    somethingElse();
}

Allman style:

while (x == y)
{
    something();
    somethingElse();
}

I recommend using one of these, though there are some others you’ll sometimes see.

Exceptions: You make break your curly brace style in the following situations:

• An if/else body has exactly one line of code. You may drop the curly braces here. You should still indent the single line.
• Some people like this if/else style that merges some curly braces and the else statement:

  if (test) {
    something();
    somethingElse();
  } else {
    aThirdThing();
    aFourthThing();
  }
  

You may use it if you like.

Variable and function names

• Variable and function names should be chosen to reflect the meaning and/or use of the variable or function. Single-character or generic names for variables (e.g., a, b, x, y, ch, num) are only appropriate when a variable is used in a very limited context, and is never used outside of that context (for instance, loop counter variables or iterator variables).
• Variable and function names typically begin with a lowercase letter. Class names typically begin with uppercase letters.
• Java normally uses “camel case” for variables, function names, and class names that have multiple words in them, which means joining the words without an underscore. Examples: numberOfTriangles for a variable name, SimpleCanvas for a class name.