There may be many opinions on how a Java file should look. The Java file layout page addresses these discrepencies and shows how a basic Java file should appear. Overall, each Emacs window should have eighty columns of characters for viewing purposes on Emacs. All lines of code should not flow over to the next if possible.

Comments:

Comments are important for many reasons. The standard for comments in Java at ISIP are given below.

The basic comment for simple purposes is just a few lines commented out with the "//" followed by a line with just "//".

	Ex:	
	 // commented information
	 // additional comments
	 //

Different sections in a Java file need to be separated out with a sort of comment separation block. This makes it visually easier to see the different sections. Sections that need to be separated are sections for different types of variables and methods. There should be a grouping of public, protected, and private variables and methods.

The block includes a line at the beginning and end of comment block that has a double forward slash followed by dashes to the edge of the window. There should be a blank line with just a double forward slash between beginning and end of dashed lines. In the middle of those four commented lines is the section description that may be one or more lines.

	Ex: 	
	 //--------------------------------------------------------------
	 //
	 // class-specific public methods:
	 //  error handler code
	 //
	 //--------------------------------------------------------------

Regular comments should be placed inside each method describing its action, but outside and just prior to every variable, method, and class definition are Javadoc comments. The next section goes into detail about Javadoc comments. Javadoc Tool

Header:

At the top of the each Java page comment header block is needed. It should contain the file's directory on the first line. The second line should have the version, date, and time, and the third line should give the author's name.

 	Ex:	
	 // file: $isip/class/java/AudioCircularBuffer/AudioCircularBuffer.java
	 // version: $Id: AudioCircularBuffer.java,v 1.6 2004/07/21 16:15:31
	 // author_name Exp $
	 //

Bracing:

Bracing becomes important when dealing with nested code. Everytime a brace is needed to start a section the open brace should be placed to the right of the section it is opening. The closing brace should be placed on the same column as the first character on the line of the opening brace. The following example would work without braces, but braces should be used anyway in this fashion.

	Ex:

	if (isEmpty()) {
	      num=0;
	 }

White Space:

Along with the proper usage of braces white space needs to be standardized. Each nested line of code should appear four spaces indented on the next line.

Operators also need proper spacing. All operators should have a space on each side for ease of reading. The example below demonstrates the correct usage of bracing, white space, and non-Javadoc comments.

	Ex:
	
	public boolean isEmpty() { 

	    // if the read and write pointer are the same
	    // then there is no data to be read inbetween them.
	    // So the circular buffer is empty
	    // 
	    if (read_position_d == write_position_d) {
	        return true;
	    }
	    else {
	        return false;
            }
        }

Go to previous page
Go to next page