Coding Standard

Assignment 5 and 6

Your goal should be "clean code that works". This coding standard will help you make the code clean.

This coding standard is the same one we used for the last assignment

New this time:

  • Rules for arrays

New for assignment 4:

  • Rules for methods

White Space and Indenting

1) Use 2 to 4 spaces to indent blocks. Do not use the tab character - it may look OK on your display but it does not always print neatly.

2) Always use the same number of spaces to indent.

3) Always indent after an opening brace '{'.

4) Put white space in your files to separate blocks of related statements.

Line Length

1) Lines must be less than 80 characters in length. Longer lines don't print correctly.

2) When you have long statements, break them so that they take multiple lines. Indent the second and following lines. The following two examples illustrate this principle. 

System.out.println("This is a line with a lot of stuff that " +
    "we want to print on the display.");

if (( airTemperature > 100 ) &&
    ( waterTemperature > 75 ) &&
    ( windVelocity < 10 ) {

Comments

1) There must be a header comment. At a minimum, it must include the following information:

  • The name of the program
  • A brief description of what the program does
  • The names of both partners
    • If you worked alone, put only your name and a comment saying why you worked alone.
  • The date

You may want to use the header comment from the first lab exercise as a template.

2) In-line comments should be included above blocks of related statements.

3) Every method must have a block comment describing it. See the method section for details.

Identifiers

1) Follow the Java naming conventions.

2) Use meaningful names that express the intention of the identifier.

If-Else and While

1) Do not have two if statements such that the first one tests for one condition and the second one tests for the opposite. Use the else statement. For example, replace:

if ( side1 == side 2 ) {
   <statements A>
}
if ( side1 != side 2 ) {
   <statements B>
}

with

if ( side1 == side 2 ) {
   <statements A>
}
else {
   <statements B>
}

2) There should be no comparisons with true or false in your predicates. For example, the if statement

while ( (airTemperature < 100) == true) {

should be written as

while ( airTemperature <= 100 ) {

3) Else if should appear on a single line. Each else should start in the same column as the first if in the sequence.

if ( surfIsUp )
   goSurfing();
else if ( isWindy )
   goFlyKite();
else if ( goodSnow )
   goSkiing();
else
   study();

4) Put the statements that make up the then and else clauses of if statements on a new line. For example, 

if ( x < 0 ) x = -x;

should be written as

if ( x < 0 )
   x = -x;
or it can be written as 
if ( x < 0 ) {
   x = -x;
}

Methods

1) Method names must reveal the intention of the method

Good

  • printTableRow()
  • getInterestRate()

Not Good

  • doIt()
  • myMethod()

2) The formal parameters must have meaningful identifier names

3) Methods should do one thing. Methods that do several things are hard to read and modify.

For example, the method printTableRow() suggested above should print one row of some table - it should not do anything else, such as calculate values, get user input, or print table headers.

4) Methods should be relatively short. In this course, you should not have methods that are more than 20 to 25 lines long. See me if you feel that you can justify having longer methods - I'm open to persuasion.

5) Methods must have a header comment. This comment must describe the method's purpose, input parameters, and return value. For example

/* getTargetAmount
 * 
 * Get the target amount from the user, which is the amount of money that the
 * user would like to have.
 *
 * Input: startAmount - the amount of money that the user is starting with.
 * Output: the targetAmount entered by the user. This routine validates the user
 *         input to ensure that the targetAmount > startAmount.
 */
static double getTargetAmount( double startAmount ) {

Arrays

1) Always use the array length instead of a constant. For example, given the definition

int count[] = new int[5];

the for loop

for (int i = 0; i < 5; i++ )
   sum += count[i];
should be written like this 
for (int i = 0; i < count.length; i++ )
  sum += count[i];

This makes it much easier to change the size of the array in your program.

2) Don't use arrays of length 1 to pass return values from methods. This is an ugly hack that can lead to unreadable and unmaintainable code.

If you find yourself doing this, your design probably needs to be re-examined. You should be able to accomplish the same thing in a simpler, clearer way.

Braces

1) The opening brace must be at the end of the statement that starts the block. The closing brace must be in the same column as the first character of the statement that started the block. For example 

if ( side1 == side 2 ) {
   <statements A>
}
else {
   <statements B>
}

or 

public static void main( String[] args ) {
  <statement 1>
  <statement 2>
  ...
}