CMSC 202 Coding Standards

Java Coding Standards

General

Every programming department has some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than six months after having written the original. While no two programming departments' standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatness counts!!!

In general we will follow the Code Conventions for the Java Programming Language as developed by the Sun Developer Network. It is your responsibility to read, understand, and use these standards. In particular, graders will be looking for you to adhere to standards regarding

file names
naming conventions
indentation and use of whitespace
comments
Comments are the programmer's main source of documentation.
From The Practice of Programming by Brian Kernighan and Rob Pike, page 23
Comments are meant to help the reader of a program. They do not help by saying things that the code already plainly says, or by contradicting the code, or by distracting from the code with elaborate typographical displays. The best comments aid the understanding of a program by briefly pointing out salient details or by providing a larger-scale view of the proceedings".

Note that we will be discussing "documentation comments" in lab.

Names

All Java classes are defined in a separate file. Name each file after the class it contains and give it a .java file extension.
For example: if you have a class that represents a Car object, the class should be named Car and the file in which it is contained should be Car.java. When Car.java is compiled, the resulting Java byte code is found in Car.class.
All class names used mixed case, with the first letter capitalized (e.g. RationalNumber).
Every data member of a class must be private.
Variable and method names used mixed case with the first letter in lowercase (e.g. grandTotal).
The use of single letter variables is forbidden, except as simple 'for' loop indices, temporary pointer variables and in special cases such as x- and y-coordinates.
The use of obvious, common, meaningful abbreviations is permitted. For example, 'number' can be abbreviated as 'num' as in 'numStudents' or as 'nr' in 'nrStudents'.
Use active function names, generally beginning with a verb and including a noun -- getName( ).
Constants (e.g. public static final double PI = 3.14;) should be used for magic numbers whenever possible.

Comments

Every .java file should contain an opening "file header comment" describing the class within the file and containing other pertinent information. This comment must be a block comment that begins with /** and include the following information.

The file name
The project number
@author Your Name Here
The date the file was created
Your section number
Your UMBC e-mail address
A statement of the class' invariant(s)

For example,

/**
* File:    Table.java
* Project: CMSC 202 Project 3, Fall 2005
* @author  Bob Smith
* Date:    9/22/05
* Section: 0304
* E-mail:  bsmith22@gl.umbc.edu 
* Class Invariant
*	1. number of legs is either 3 or 4
*   2. shape is one of ROUND, RECTANGLE or OVAL
*/

Method Comments

Method comments are the primary form of documentation for the user of our class methods. It is important that this documentation be both complete and accurate as it forms a "contract" between the class user and and the class implementer. These comments are sometimes refered to either "documentation comments" or "interface comments".

Each class method must have a comment that includes the following information.

The method's name
The method's pre-condition(s)(if there are no pre-conditions, say so).
The method's post-condition(s)
Appropriate JavaDoce "@ tags". We will be learning about the JavaDoc automated documentation process and its special tags in lab.

A pre-condition is a statement giving the condition(s) that is (are) required to be true when the function is called (see text page 207). The function is not guaranteed to perform correctly unless the pre-conditions is true (are). It is NOT just a restatement of the parameter names and types.
All functions must test for pre-conditions to the extent possible Until we learn about exceptions, if a false pre-condition can be handled in code, do so (see CircleArea function below).

A post-condition is a statement describing what will be true when the function call is completed (assuming the pre-condition is met and the function completes; see text page 207).

For example, a method that calculates the area of a Circle might have a header like this

/**
* Name: CircleArea
* PreCondition:  the radius is greater than zero
* PostCondition: Returns the calculated area of the circle
* @params radius - the radius of the circle
*/
double CircleArea ( double radius )
{
   // handle unmet precondition
   if (radius < 0.0)
      return 0.0;
   else
      return Math.PI * radius * radius;
}