Style Guide for CS 159

This Style Guide should be used as a reference for all work turned in for credit, both labs and programming assignments. It is based on (but not identical to) standard java coding guidelines including the Sun Java Coding Conventions and the Code Style Guidelines for Android.

Names

All names should be descriptive and readable: subTotal rather than s; grade rather than grd. Multiple word names should use a capital letter to separate words (e.g. subTotal). Variable names should balance clarity with brevity. The name person is better than currentPersonObject. However, per is worse than either (percentage? person? permitted?).

Variable and method names must begin with a lower-case letter, for example, subTotal

Variable names should be nouns or noun phrases (e.g. studentName or subTotal)
Method names should be verbs or verb phrases (e.g. printLine or addColumn)

Class, interface, and enumerated type names should begin with a capital letter and use title case (e.g. HelloWorld).
Constant names should be all caps with an underscore separator (e.g. PI, INTEREST_RATE).

Declarations

Where and when to declare variables.

You must declare all constants and variables at the top of the method or class in which they are used. Constants must be declared first followed by a line of white space and then variables.
Each variable or constant must be declared on its own line.
Constants must be declared and initialized when created.
Variables may be initialized when declared if an initialization is necessary. DO NOT initialize variables when it is unnecessary.
The loop control variable of a for loop may be declared within the body of the loop (inside of the for loop header).

Indentation

Indentation provides a visual structure for your program.

Code blocks must be indented 4 spaces.
Line wraps must be indented 8 spaces.
Curly braces for code blocks must line up vertically and the open brace must line up directly beneath the first letter of the header for that block.
All blocks of code (even if one line) should be surrounded by curly braces.
Always use spaces, not tabs, for indentation.

Operators

Binary operators should be separated from their operands by a single space on either side for readability. Unary operators must not have a space.

Examples: sum = myGrade + yourGrade; myGrade++;

An exception is the dot (.) operator which does not have space surrounding it.

Example: System.out.println();

Resolve operator precedence with parentheses.

Example: pay = (hours * 1.5) + bonus;

Structure

Structure provides readability.

One line of white space must follow the declaration of constants and variables.
Use single lines of white space to separate segments or blocks of code.
In a class declaration, fields (class attributes and instance variables) must be declared first. Constructors must come next and precede all other methods.
Line lengths must be less than 100 characters.

Comments

The point of comments is to clarify code that might otherwise be difficult for the reader to follow. Well organized Java code with informative variable names should require few comments inside of method bodies.

In-line comments must come before the code that they are describing or, if brief, on the same line following the code.
You must use normal English spelling and grammar. Phrases are okay, but cryptic abbreviations and unintentional misspellings are not.

Documentation

Every class must include a Javadoc comment like the following.

       /**
	* Overall description of the class goes here
        *
	* @author Your name goes here
	* @version Vn -date (date may be in MM/DD/YY or MM/YY format)
	*/

All methods must contain a Javadoc comment preceding the method header as shown in the example below. The description should describe the "black box" behavior of the method (what it does). If there are parameters, then there must be one @param tag for each parameter in the format shown below. If there is a return value, there must be one @return tag which describes the return value (not the variable name). Finally, if the method throws one or more exceptions, @throws tags must be used to describe the circumstances under which each exception will be thrown.

      /**
      * Overall description (black box behavior) of the method goes here.
      *
      * @param parameterName Describe each input parameter. You must have one
      * @param line for each parameter
      * @return Describe the value that this method returns.
      * @throws ExceptionName Describe under what conditions the exception may 
      * be thrown
      */

Acknowledgments

Every programming assignment must contain the following section which follows the class description or must cite any sources used (such as a TA). You should either include this statement in all files or minimally it may appear in the file containing your main method.

       /*
	* References and Acknowledgments: I received no outside help with this
	* programming assignment.
	*/

       /*
	* References and Acknowledgments: TA Glenn helped me with the 
	* foo method.
	*/

This acknowledgment is not necessary for lab assignments. Note the single star after the slash; this is not a Javadoc comment.

Miscellaneous

Normally, methods that return a value should have a single return statement.
Avoid "magic numbers". Use named constants instead of literal values when you need to specify a constant value in your code. (e.g. Math.PI rather than 3.14159)
Your code must not have unused variables or unnecessary statements (statements that do nothing).
Your code must not have empty blocks of code. Do not use an else if it is not needed.
Avoid the use of break and continue except in switch statements.
All instance variables should be declared private unless there is a documented reason for not doing so.
Class constants may be public if they are provided as a service to outside classes (such as Math.PI).
All visibility modifiers should be explicitly stated.
Avoid using * to import entire packages. (e.g. import utilities.GoodClass; instead of import utilities.*;)