CS133: Developing Programming Principles

CS 133 Programming Style Guide

A portion of each assignment will include marks for programming style and documentation. These are essential to producing code that is easy to read, understand, and use. Following these conventions makes it easier for the markers to understand what you are trying to accomplish, which makes it easier for them to find marks to give you, especially if you did not complete the entire assignment.

For your programs in CS 133, these guidelines are required. Some of these style guidelines result from idiosyncrasies of the instructors and other course personnel, and they may not be the style you prefer. This cannot be avoided in any style guidelines. It is worth noting that every software development company has their own standards and that you will dislike parts of those as well, but you will nevertheless be expected to follow them.

Javadoc

The code you write for CS 133 must be well-commented. In the interest of providing a consistent style, we strongly recommend that you use Javadoc in your comments so that the markers know where to look for information about your code; however, it is optional so long as you provide the same information. These comments must include:

a brief (Javadoc) description of each class before the class declaration
a brief comment describing the purpose of each instance variable
a brief (Javadoc) description of each method immediately before the method declaration, including a short description of the method purpose, each of the parameters, and the return value (if applicable) (you can use the @param and @return Javadoc tags if you like, but they are optional)

All comments should be as concise as possible. They should avoid stating the obvious. For example, this is good

	int lineCounter; // Of line most recently read from file

and this is bad

	int lineCounter; // A variable to count lines.

Pre-conditions and Post-conditions

Pre-conditions and post-conditions are optional in CS 133. If you use these, they should be the last comments in the method documentation.

Indentation

Consistently indent the bodies of loops, if-else clauses, method bodies, and class contents. Use the same number of spaces for each (3-4 spaces is the usual amount recommended). You can use DrJava's default indentation for this. If you add or remove loops, if statements, or other constructs that indent code, be sure to go back and reset the indentation for any code that may be affected.

Blank Lines

Use blank lines to delimit logically distinct blocks of code. Use blank lines to separate methods. Use blank lines to separate instance variable declarations from methods.

Spaces

Add spaces between parameters and arguments. That is, write

	public void putPeg(Color colour, int row, int col)

	b.putPeg(Board.YELLOW, 2, 3);

and not ,

	public void putPeg(Color colour,int row,int col)

	b.putPeg(Board.YELLOW,2,3);

Some people like to add space after the first and before the last parentheses and write

	public void putPeg( Color colour, int row, int col )
	
	b.putPeg( Board.YELLOW, 2, 3 );

This form is also acceptable.

Also, add spaces around operators and assignment statements. This is good

	counter = 2;

	counter = counter + 3;

and this is bad

	counter=2;

	counter=counter+3;

Structured and Meaningful Variable Names and Constants

All variable names start with a lower-case letter. If you use a noun phrase with several words, capitalize the first letter of all subsequent words. For example

	double interestRate;

	String fileName;

	int userChoice;

All variable names should be meaningful and indicate their purpose. The only exception to this are simple loop variables (generally, these are variables in for loops that progress in a straightforward manner).

Constant names are all upper-case letters, using underscores to separate words in a noun phrase. The name of a constant must indicate what it represents. You cannot have any "magic numbers" in your code---these should be constants with a good name.

For example, to create a chess board with the Board class, the following is good

	public final int BOARD_SIZE = 8;
                
	chessBoard = new Board(BOARD_SIZE, BOARD_SIZE);

and this is bad

	chessBoard = new Board(8, 8);

Variable Declarations

These guidelines apply to local variables in a method and instance variables for a class.

Only one variable should be declared per line. It can be initialized in the declaration if you wish.

All variables should be declared in a block at the top of the scope in which they are used. There should be a blank line between the last variable declaration and the start of any code in that block. (The only exception is declaring loop variables inside of a for loop.)

Each variable should be commented with its purpose. You can do this in one of two ways. The comments for each variables can be placed on the right hand side of the declaration on the same line (comments for multiple variables must be lined up). Alternately, comments can be placed on the preceding line, with blank lines between variables. Pick an alternative and use it consistently.

This is good

	String currentWord = "";      // The word just read in.
	int lineNumber;               // Line number of current word.

and this is good

	// The word just read in.
	String currentWord = "";

	// Line number of current word.
	int lineNumber;

This is bad

	String currentWord = ""; // The word just read in.
	int lineNumber; // Line number of current word.

and this is also bad

	// The word just read in.
	String currentWord = "";
	// Line number of current word.
	int lineNumber;

Class Names

Class names start with an uppercase letter.

Method Names

Method names start with a lower-case letter.

Lines of Code

Each line of code can only contain a single statement. This is good

	counter = 0;
	nextWord = scanner.next();

and this is bad

	counter = 0; nextWord = scanner.next();

Also, all lines should be kept to a maximum of 120 characters. This is to improve readability when assignments are printed out to be marked.

Compound Statements for Classes and Methods

There are two possible formats, either of which are acceptable.

The braces for the start and end of each class and method must start on their own separate lines and must line up. This is good
```
	public class Rectangle
	{
	    public int area()
	    {
	         // Implementation
	    }
	}
```
The opening brace is on the same line as the class or method declaration, while the closing brace is on its own separate line.
```
	public class Rectangle {
	   public int area() {
               // Implementation
	   }
	}
```

Compound Statements for If-Else and Loops

Always use compound statements for the body of any if-else or loops, even if they consist of a single statement. This makes it easier to add or remove code later.

Braces can placed be on separate lines and lined up (as with classes or methods). Alternately, the opening brace can be on the same line as the if-else or loop. The following are good

	if (!scanner.hasLine()) {
	     done = true;
	} else {
	     done = false;
	}


	if (!scanner.hasLine())
	{
	     done = true;
	}
	else
	{
	     done = false;
	}

This is bad

	if (!scanner.hasLine())
	    done = true;
	else
	    done = false;

Visibility of Program Elements

All classes are to be declared public.

All instance variables are to be declared private.

Constants can be either public if they are relevant outside of the class, private otherwise.

Methods that are meant to be called from outside the class are to be declared public. Helper methods (those that are meant to be accessed only from inside the class) are to be declared private.

Accessor and Mutator Methods

Only define accessor and mutator methods as they are needed. If there is no reason for an instance variable to be changed or doing so is unwise, do not provide mutators (as was done with the Coordinate class). If you do not wish to make an instance variable available to other classes, do not provide accessors (as was done with the Board class).