Introduction to Java Programming - Building Java Programs: A Back to Basics Approach - page 22

Here are some simple rules to follow that will make your programs more readable:

• Put class and method headers on lines by themselves.

• Put no more than one statement on each line.

• Indent your program properly. When an opening brace appears, increase the

indentation of the lines that follow it. When a closing brace appears, reduce the
indentation. Indent statements inside curly braces by a consistent number of
spaces (a common choice is four spaces per level of indentation).

• Use blank lines to separate parts of the program (e.g., methods).

Using these rules to rewrite the Ugly program yields the following code:

1 public class Ugly {
2 public static void main(String[] args) {
3 System.out.println("How short I am!");
4 }
5 }

Well-written Java programs can be quite readable, but often you will want to
include some explanations that are not part of the program itself. You can annotate
programs by putting notes called comments in them.

Comment
Text that programmers include in a program to explain their code. The
compiler ignores comments.

There are two comment forms in Java. In the first form, you open the comment with
a slash followed by an asterisk and you close it with an asterisk followed by a slash:

/* like this */

You must not put spaces between the slashes and the asterisks:

/ * this is bad * /

You can put almost any text you like, including multiple lines, inside the comment:

/* Thaddeus Martin
Assignment #1
Instructor: Professor Walingford
Grader: Bianca Montgomery */

The only things you aren't allowed to put inside a comment are the comment end
characters. The following code is not legal: