Java Program Style Rules

Copyright 1998-2003 Clinton Staley

All Rights Reserved

(Last update 5/6/03)

The following style rules are mandatory for all programs submitted. Breaking a style rule will cause your program to bounce, and you will have to redo the code according to correct style. Because in-class examples were written according to earlier versions of this style sheet, some of them may differ from the rules here. Be sure your submitted code follows this style sheet when theres a difference.

1. Identifier Names

A. Use meaningful variable names. X, jj, and bobo don't mean as much as timeLeft, biggest, and whereNext.

B. Avoid single letter variable names, except as loop counters in for-loops.

C. If you decide to abbreviate a commonly used term in variable or type names, use exactly the same abbreviation everywhere. (For instance, if the term "category" appeared often in variable or type names, you might abbreviate it everywhere to "ctg".)

D. In multiple-word names, capitalize the first letter of the second and later words. Do not use underscores. Capitalize the first letter of class names. Leave the first letter lowercase in methods, locals and member data. Begin all nonpublic member data with "m". Final data must be in all-caps, with underscores separating words.

Classes Functions and locals Nonpublic member data Final data

String stringLength mCount MAX_SIZE

BigView clearList mData BUTTON_COLOR

E. Do not use Hungarian notation. However, do add an "m" ahead of each member datum name. (Member data names might be mCount, mCurrentItems, etc.) This helps avoid bugs due to accidentally naming a local variable and a member datum identically.

2. Comments (for assignments requiring commenting)

A. Write comments for each method that is not baldly obvious (such as a simple accessor), including a description of what the function does, and what each parameter is for. If the function makes any special assumptions about the contents of the parameters, list these. Write comments for each class in the program, including descriptions of each member datum. Don't comment the obvious; concentrate on explaining the hard parts.

B. Use JavaDoc notation for all comments.

C. Comments must be clear. A set of words in comment markers is not automatically a comment. Comments must be grammatical and correctly spelled.

D. Put comments that exceed one or two lines in function headers, not in the code itself. You may mark a line with a number thus: // 1 , and discuss it in the function header.

3. Finals

Use static final data in your code instead of direct numbers. There must be no actual numbers other than 0, 1 or 2 in your code, unless an exception has been granted by your instructor.

4. Class Design

A. Avoid parameter lists of more than 5. Group data into structs or classes instead. For instance:

void PrintStats(int total, int count, int mean, int median, float stddev)

These parameters are related; they comprise a set of statistics. Instead of passing 5 items, group them into a single class and pass just one object.

B. Never use public member data in an outer class. If you have a member that you would like to make freely modifiable, make the data member private or protected, and create two public member functions to access and modify it, using the same name as the data member, but with get or set prepended:

class Type {

public int getData(void) {return mData;} // Get data value

public void setData(int val) {mData = val;} // Modify data value.

private int mData;

}

This arrangement lets you attach more complex code to the accessing and modifying of data in the future.

C. In small inner classes -- those that would be represented with a "struct" in C++ -- you may make all member data public. Such classes should have at most a constructor and perhaps a utility method like clone. Their member data need not begin with "m". Classes more sophisticated than this must have no public member data.

D. All member data and methods must have access modifiers (protected, private, or public). Default access (package access) is forbidden except when specifically allowed in special cases.

E. Functions must be at most 50 lines long, not counting blank lines, asserts, comments, or lines with only a single brace on them. Don't cram code together to satisfy this limit. Break up your functions instead.

F. Place inner classes at the top of the class declaration, followed by member data, and finally by methods.

G. Place all local variable declarations at the top of the function, with a single blank line separating the locals from the code that follows.

5. Indentation and Blank Lines

A. Use 3 space indentation.

B. Indent only one level for each nested if, while, or switch:

while (...) {

statement;

if (...) {

statement;

}

}

C. Never let a line exceed 80 columns. If a line must be broken into two, indent the second part one space past the first column of the first part:

Big long line....

with continuation line below

D. Indent both the then and else blocks of an if-statement, even if they are only one line long. Don't write: if (test) statement;

E. Use blank lines to break up blocks of code. Your code should fall into groups of about 5 lines on average, separated by a blank line or a line with only a brace, and possibly started with a one or two line comment. Always put a blank line after the local declarations in a function. Dont put more than one blank line in a row. A single blank line at a time is enough to break up the flow of code properly.

F. Always place the opening brace at the end of the if, while, class, etc. line that it applies to, and place the closing brace on a line by itself, in the same column as the beginning of the opening line.

G. Indent the code inside of a class 3 spaces relative to the "class" keyword.

H. Functions must either fit entirely on the line to the right of the function header, or must be broken up over multiple lines.

public int total(void) {Code for total}

OR

public int total(void) {

Code for total;

Code for total;

}

I. Branches of an else-if sequence must be indented at the same level, even though technically each else-if should be indented one level deeper than the preceding one.

J. Do not put more than one statement on a line.

6. Spacing

A. Use spaces to clarify your program and to break up long expressions, but don't overdo it. Put spaces after each comma, and around each keyword (note that "if", "while" and "for" are keywords). Put a space after each semicolon in a for header. Never put a space before a comma or semicolon.

B. Put spaces around operators, except in very large expressions where you may avoid them around the highest-priority operators. Dont have more than three variables or operators in a row without a blank space.

Good: epsilon = 2*beta + gamma - delta*pi;

Bad: epsilon=2*gamma-delta*pi;

C. Don't put space after an opening paren, or before a closing one. Do not put space between a function name and the opening paren for the parameter list.

7. Code Elegance

A. Do not ever use the clauses "== true" or "== false" in code. Use boolean variables as direct tests, as in "if (mEmpty)", not in equality checks like "if (mEmpty == true)".

B. Do not write an if-else that can be replaced with a simple boolean expression. For instance:

if (val1 < va2 && mark == 0)

oddTest = true; VS: oddTest = val1 < val2 && mark == 0;

else

oddTest = false;

C. Don't explicitly initialize member data to 0 or null; such initialization is guaranteed by the language.