Programming Style - Multimedia Introduction to Programming Using Java - page 373

2. The implementation of a statement comment has the same level of inden-
tation and has a blank line after it.

When only two levels of abstraction are used —a statement-comment and its
implement, which contains no statement-comment— the second convention is
satisfactory. But if the implementation of a statement-comment itself contains a
statement-comment, the second convention simply does not work. In Fig. 13.7,
where does the implementation of the first swap statement-comment end? At the
first blank line underneath it. Then where does the implementation of the per-
mute statement-comment end? At the first blank underneath it? The structure of
the program is simply not evident from the indentation.
In this text, we tend to use the second alternative for indenting statement-
comments, even though it is inferior, simply because that is what the field does.
However, if the implementation of a statement-comment contains a statement-
comment, we resort to the first alternative to make the structure clear.
One final point. If statement-comments get several levels deep, it is time to
reorganize that piece of program, perhaps by writing a method or two, to remove
some of the levels.

13.4 Describing variables

It is difficult to understand statements that use variables unless one knows what
the variables mean. Typically, variables are described in comments that accom-
pany their declarations. Here, we discuss how to write these comments.

/** Instance: sale of a number of items at a price, e.g. 3 for $1.29 */
public class ItemSale {
private String name; // name of item being sold
private int groupCount; // groupCount items cost grpPrice cents
private int groupPrice;
private int numSold; // number of items sold

...
}

Figure 13.8 Some fields in class ItemSale

/** Instance: sale of a number of items at a price, e.g. 3 for $1.29 */
public class ItemSale {
// name is the name of the item being sold; groupCount of them cost groupPrice cents
private String name;
private int groupCount;
private int groupPrice;

private int numSold; // number sold

}
Figure 13.9 Placing field comments above their declarations