Programming Style

Opening block comment

Your program should begin with a block comment using the following template:

/**
* Assignment #1.
* This program adds up some coins and prints the total value.
*
* Authors: Charlie McDowell (mcdowell@ucsc.edu)
* and Jane Programmer (jprogrammer@ucsc.edu)
*/

Program Name

Your program names should always begin with an uppercase letter and then use lowercase except to separate embedded words (as in CountChange). Check the program specification which may mandate a specific name for the main class.

Variable Names

Your variable names should begin with a lowercase letter, and use uppercase to separate embedded words (as in someVariableName). The variable names must be descriptive English words. There are only a few exceptions to this and they will be discussed in class (e.g. i is an acceptable loop index if it is indeed an arbitrary index into an array). It is better to err on the side of long and descriptive (use "index" instead of "i", use "quarters" instead of "q").

Proper Indentation

You must use proper indentation. See the examples in the book. Each opening brace "{" must be followed by additional indentation of between 2 to 4 spaces. Each closing "}" must be on a line by itself and aligned directly below the matching "{" or the keyword on the line containing the matching "{" if the "{" is not on a line by itself. E.g.

if (test) {
 doSomethingHere();
}

or

if (test)
{
 doSomethingHere();
}

No Tabs

The source files you submit MUST NOT contain any tab characters. The problem with tab characters is that different editors set different tab stops. You can use the unix expand command to remove tabs before submitting your program. If you use DrJava as your editor then it will automatically use spaces instead of tabs for indenting.

NOTE: It is perfectly fine, and even encouraged, to use tabs while programming. Many editors, such as emacs do a nice job of automatically indenting Java source files. Just remove the tabs before submitting your code.

No Long Lines

Limit your source lines to 120 characters. Keeping the lines within 120 characters makes it easy to view the source code from many different editors without worrying about unexpected line wrapping.

Block Comments on Methods

Every method should have a javadoc style comment that describes what it does including all parameters, any assumptions the method makes and any return value. Here is an example from a TicTacToe program:

/**
 * Try to put the specified player's mark (X or O) at the indicated row and col (0-2).
 * If successful, then return the other player else return the same player.
 * @param col - 0-2 the selected col
 * @param row - 0-2 the selected row
 * @param board - the array used to store the moves
 * @param player - the current player 'x' or 'o'
 * @return either the next player if the move was legal, or the current player o/w
 */
char mark(int col, int row, char[][] board, char player) {

No Magic Numbers

Your programs should not contain "magic numbers." A magic number is a literal constant (with the exception 0, +1, and -1) appearing more than once with the same meaning anywhere in the source of a program. If a numeric literal occurs only once, then creating a constant is not mandatory but still often helps with documentation. A comment on the line explaining the literal will generally suffice for single use literals.

Use if-else-if-else when called for

Do not use a series of if-statements when at most one of the conditions is expected to be true. Instead use if-else-if-else-if...

No "break"

Do not use break except in switch statements.

Proper use of boolean

Do not use an integer where a boolean is called for. E.g. don't use "while (hasMoreInput == 1)...", use "while (hasMoreInput) ...".

Do not test against true of false, just use the boolean expression itself instead. E.g use "while(hasMoreInput)" instead of while(hasMoreInput == true)".

No Loooong Methods

Except in the case of an if-else-if.. or switch statement with many cases, each of which is at most 2 or 3 lines long, break methods that are over 50 lines into smaller subparts. Ideally methods should be 25 lines or less.

No Globals

Global variables (class variables) are not allowed. You may have global class constants that include the keyword "final".

Don't Miss Opportunities for Methods

Avoid repetitive sequences of lines that could/should be easily converted into a method.