Java Coding Standards


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

  1. file names
  2. naming conventions
  3. indentation and use of whitespace
    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.



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.
  1. The file name
  2. The project number
  3. @author Your Name Here
  4. The date the file was created
  5. Your section number
  6. Your UMBC e-mail address
  7. A statement of the class' invariant(s)
For example,
* File:
* Project: CMSC 202 Project 3, Fall 2005
* @author  Bob Smith
* Date:    9/22/05
* Section: 0304
* E-mail: 
* 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.

  1. The method's name
  2. The method's pre-condition(s)(if there are no pre-conditions, say so).
  3. The method's post-condition(s)
  4. 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;
      return Math.PI * radius * radius;