Java Coding Style (UNDER CONSTRUCTION)

15-212, Spring 1998

Appearance
Documentation
Program Structure

A consistent style in coding makes a program easily readable by anyone (including the original author!). Here are some guidelines. You may also look at the Java standard libraries, e.g., StringBuffer and other classes in java.lang.

Appearance:

Indentation:

Good, consistent indentation is essential. Badly indented code can drive the reader crazy, and is sufficient cause for retribution! Some editors (such as X-Emacs) help with this, and promote a consistent appearance.

A block of code nested inside { } is indented 4 characters. If, while, switch statements have their associated statements similarly indented:

	{
	    i = 10;
	    j = 20;

	    if (i == j) {
		do this;
		do that;
	    } else
		do soemthing else;

	    switch (i) {
	    case 1:
		do something;
		break;
	    case 2:
		do something else;
		break;
	    default:
		break;
	    }

	    while (i < 20)
		i++;
	}

Study the style followed in examples. Some editors might support somewhat different indentation. Minor variations from the above are acceptable, so long as they are consistently followed.

Spacing:

To improve readability, use blank lines in separating major pieces of code. For example, between variable declarations in a class or method, and the rest of it, and between major steps in a method body. (See Stack.java, presented in class, for an example.)

Documentation:

Naming Conventions:

Use meaningful names for class member variables and methods, as well as the more important local variables in methods. Well chosen names go a long way towards good documentation. Do not abbreviate names to the point of being cryptic. Also, follow these commonly used conventions:

Class names begin with a capital letter, and multi-"word" names begin each "word" with a capital letter:
```
	public class String
	public class StringBuffer
	
```
Variable and method names begin with a lower case letter. Multi-word variable and method names begin each word, except the first, with a capital letter:
```
	char buffer[];
	int bufferLength;
	void setBufferLength(int length)
	
```
Do not use underscores in multi-word identifiers. Use capitalization as mentioned above.
final constant identifiers are in all upper case. (These may have underscores for readability.) E.g.:
```
	public static final int MAX_VALUE = 0x7fffffff;
	
```

Comments:

A program devoid of comments, or full of content-free comments is equally frustating to the reader. Document the functionality of your code. There are three kinds of comments in Java, outlined on p.20 of Java in a Nutshell by Flanagan.

Use a /* ... */ style comment at the beginning of each file to document the evolution of the file. Include the date, name (author), and the purpose of each update made to the file.

Use /** ... **/ style comment to document the overall function of a class, and each member variable and method inside each class. (Though the language specification actually ends such comments with */, it is more readable to close them with **/. Place such comments just before the respective class, variable, or method.

If there are several obvious ways of implementing a class and you chose one for some reason (efficiency, simplicity, etc.) document it.

Document the purpose of each class variable. For methods, summarize the meaning and valid ranges of input parameters (if any), the function performed within the method (including modifications to data structures) and the return values (if any). It should also specify any exception or error conditions.

The utility javadoc can parse /** ... **/ style comments to create html documentation (see pp. 233-234 of Java in a Nutshell). Hence, it is useful to include html tags in such comments for better readability of the generated documentation. See StringBuffer for examples. (But you are not required to do so for this course.)

Use /* ... */ and // style comments to document the execution flow in each method. That is, provide an informal summary of each major step just prior to it. (See the body of the main method in NthFromEnd.java, presented in class.)

Program Structure:

Modularity:

This is the hardest to define in such a document. One good measure of program structure is the granularity of each method in any class. A method should preferably be visible in its entirety in an editor window. This is usually an indication that the method is designed to perform one, well-defined function. That is, it is an indicator of the modularity of the design. A long multi-page method is probably ill-designed, attempting to tackle too many operations under one function.

Methods that have a long parameter list are, again, ill-designed. The longer the list, the harder it becomes to remember the interface specification.

Define classes and methods to be modular. This is easier said than done. And, in any serious size project, the right modularization is only achieved after multiple iterations.

Efficiency:

Programs should run with reasonable efficiency. This topic will be covered rigorously in the theory portion of the course. For now, one should use common sense to ensure that programs do not consume an inordinate amount of memory or CPU resources.

Ravishankar Mosur

Last modified: Mon Feb 16 19:18:36 EST 1998

Java Coding Style (***UNDER CONSTRUCTION***)