Programming Style and Documentation

Good programming style and proper documentation make a program easy to read and help programmers prevent errors. Programming style deals with what programs look like. A program can compile and run properly even if written on only one line, but writing it all on one line would be bad programming style because it would be hard to read. Documentation is the body of explanatory remarks and comments pertaining to a program. Programming style and documentation are as important as coding. Good programming style and appropriate documentation reduce the chance of errors and make programs easy to read.

Appropriate Comments and Comment Styles

Include a summary at the beginning of the program that explains what the program does, its key features, and any unique techniques it uses. In a long program, you should also include comments that introduce each major step and explain anything that is difficult to read. It is important to make comments concise so that they do not crowd the program or make it difficult to read.

In addition to line comments (beginning with //) and block comments (beginning with /), Java supports comments of a special type, referred to as javadoc comments. javadoc comments begin with */**** and end with **/. They can be extracted into an HTML file using the JDK’s **javadoc* command. Use javadoc comments (/** … /) for commenting on an entire class or an entire method. These comments must precede the class or the method header in order to be extracted into a javadoc HTML file. For commenting on steps inside a method, use line comments (//*).

Proper Indentation and Spacing

A consistent indentation style makes programs clear and easy to read, debug, and maintain. Indentation is used to illustrate the structural relationships between a program’s components or statements. Java can read the program even if all of the statements are on the same long line, but humans find it easier to read and maintain code that is aligned properly. Indent each subcomponent or statement at least two spaces more than the construct within which it is nested.
A single space should be added on both sides of a binary operator, as shown in the following statement:

System.out.println(3+4*4); Bad style
System.out.println(3 + 4 * 4); Good style

Block Styles

A block is a group of statements surrounded by braces. There are two popular styles, next-line style and end-of-line style:

public class Test
{
public static void main(String[] args) { System.out.println("Block Styles"); }
}

Next-line style

public class Test {
public static void main(String[] args) { System.out.println("Block Styles"); }
}

End-of-line style

The next-line style aligns braces vertically and makes programs easy to read, whereas the end-of-line style saves space and may help avoid some subtle programming errors. Both are acceptable block styles. The choice depends on personal or organizational preference. You should use a block style consistently—mixing styles is not recommended.