Style Guide for CS 239

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 a capital letter to separate words (e.g. subTotal). Code should be self-documenting.

• Variable and method names must begin with a small letter, for example, subTotal 
• Variable names should be 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 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. This exception is due to the way JGrasp does automatic indentation.
• 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. 
• 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.
• Lines should 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,and @exception
• You must use normal English spelling and grammar.  Phrases are okay, but cryptic abbreviations and unintentional misspellings 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).  You should either include this statement in all files or minimally it may appear in the file containing your main method.

        /**********************************************************************
	* 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 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
      ***********************************************************************/
      

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 application via the command line arguments.

Miscellaneous

• Your code must have a single entry point and exit point for the main method and all called methods.  For value returning methods, the return statement must be the last line of the method.
• Use constants instead of literal values when that value has meaning.  (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.
• 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. HINT: Don't use break or continue except for switch statements.
• 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.

---

This style guide is adapted from Nancy Harris's CS239 Style Guide.