CS257: Java Documentation and Style Requirements

---

1. Proceeding each class definition, there must be a block comment in the following format:

/**

* Write a description of the class here.

*

* @author (your name)

* @version (a version number or a date)

*/

2. Proceeding each method definition, there must be a block comment in the following format:

/**

* Write a description of the method here.

*

* @param y purpose of parameter y. One line for each parameter.

* @return brief description of the return value

*/

Using the formats shown here allows descriptive html documents to be automatically generated by javadoc.

3. Blocks of code should be consistently indented and aligned. Indenting is VERY important for code readability. Each statement in the same block should be at the same level. In any statement that introduces a new block of code, the new block should be indented one level.

4. Code should not be allowed to ‘soft’ line-wrap. If code is longer than one line, the programmer should break the line at an appropriate place by inserting a return character.

5. One of the following two brace-aligning styles should be used:

if (i > 0) {

i = 10;

}

if (i > 0)

{

i = 10;

}

Notice that the closing brace is at the same indentation level as the keyword it closes.

6. Closing braces for long blocks of code should have a brief comment indicating the construct with which they are associated, e.g.,

} // end while

Example:

 
/**
* A class that describes objects that store a String.
* 
* @author Pete Nordquist 
* @version January 3, 2004
*/
public class HelloWorld
{
 
 // instance variable - HelloWorld objects store a String
 private String x;
 
 /**
 * Initializes the String stored by this object
 * @param s The string the new object stores
 */
 public HelloWorld(String s)
 {
 // initialize my instance variable
 x = s;
 }
 
 /**
 * Special method that starts a stand-alone program.
 * @param args the arguments passed to the program
 */
 public static void main(String args[])
 {
 // declare a variable that will point to a HelloWorld object
 HelloWorld hw;
 // create a HelloWorld object and have it store the string 
 // "Hello World". Then assign the pointer returned by "new" 
 // to the variable I declared to store this pointer.
 hw = new HelloWorld("Hello World!");
 // print the String my new object is storing
 System.out.println(hw.getString());
 }
 
 /**
 * Allows user to return the String stored by this object
 * @return the String this object is storing
 */
 public String getString()
 {
 return x;
 }
}