Style Guide for CS 239 - Spring 2009

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.

Names - All names should be descriptive and readable. subTotal rather than s; grade rather than grd. Multiple word names should use either a capital letter separate words (not both). subTotal. Think about self-documenting code.

Variable and method names should begin with a small letter. subTotal

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

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

Declarations - Where and when to declare variables

All variables and constants should be declared at the top of the method or class in which they are used. Constants should be declared first followed by a line of white space and then variables.
Each variable or constant should be declared on its own line.
Constants should be declared and initialized when created.
Variables may be initialized when declared if an initialization is necessary. DO NOT initialize all variables.
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.

Sub sections of code must be indented consistently, with at least 3 spaces for readability.
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. An exception to this rule is that you may have the first line of a method header one space to the right of the curly brace (an exemption due to the way JGrasp automatically indents.
Continuation statements must be indented 1 space for the 2nd and subsequent lines.

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. Ex: System.out.println();

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.
Lines must be kept to a short length (<80). You should be able to see the full line in your editor and in the submit system.

Comments - Comments provide a guide to what the program is doing.

In-line comments must come before the code that they are describing or if brief on the same line following the code.
Javadoc style block comments(/** */) describe each class and method. Such comments must include the appropriate tags: @author, @version, @param, @return, @exception
You must use normal English spelling and grammar. Phrases are okay, but cryptic abbreviations are not.

Class description - every class file must contain a description formatted 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)
*
***************************************************************************/

Programming Assignments - Every programming assignment must contain the following section which follows the class description or must cite any sources used (such as a TA).
/***************************************************************************
* References and Acknowledgements: I received no outside help with this
* programming assignment
*
***************************************************************************/
OR
/***************************************************************************
* References and Acknowledgements: TA Glenn helped me with the foo method.
*
***************************************************************************/

This acknowledgement is not necessary for lab assignments.

Methods - All methods must contain a javadoc comment preceding the method header which contains the following if applicable. Make sure that you do not give an @param or @return tag for methods that take no parameters or which do not return a value. If the method throws an exception you should also have an @throws tag.
/***************************************************************************
* Overall description of the method goes here
*
* @param paramterName Describe each input parameter, must have one @param line for each
* @return Describe the value that this method returns.
* @throws ExceptionName Describe under what conditions the exception may be thrown
***************************************************************************/

NOTE: In the main class (the class that contains the main method) your method description may reiterate the class description but should contain a detailed description of any arguments being passed into the method.

Miscellaneous

In general, your code should have a single entry point and exit point for the main method and all called methods.
You may use the break and continue statements within a loop, but you may lose points if they are used incorrectly or where there is a better solution to ending the loop.
All class fields (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.