Page 337 - Introduction to Programming with Java: A Problem Solving Approach

} // end setFirst
Why is that good practice? So someone reading the program can quickly identify the block that is being ended without having to scroll to the top of the block to find out. It’s OK to omit closing-curly-brace com- ments for short blocks of less than about five lines. For short blocks, it’s easy to tell what block the closing brace is attached to, and the final comment just adds clutter.
Include comments for code segments that would not be obvious to a typical Java programmer. In Figure 8.2b, notice this comment that appears at the tops of the bodies of the setFirst and setLast methods:
// [A-Z][a-z]* is a regular expression. See API Pattern class.
This comment is helpful because the subsequent statement is more obscure than most.
The comment should either explain directly or help the programmer find more informa-
tion on the topic, or both. A comment like this that references an authoritative source
is especially important whenever code implements something mysterious—an arbitrary definition like the “regular expression” above, a formula with empirical coefficients, or a mysterious mathematical expression.
Whenever a comment is too long to fit at the right of the line that is being explained, put it on one or more lines by itself above the line that is being explained. The // should be indented the same as the de- scribed line. If you put a comment on a line by itself, make sure there is sufficient whitespace above it. In the setFirst and setLast methods of Figure 8.2b, there’s sufficient whitespace above the comments because the prior lines happen to be opening braces for their respective method bodies. In other cases, you’ll need to insert a full blank line above the comment. It’s optional whether you insert a blank line below it.
8.2 Coding-Style Conventions 303
Apago PDF Enhancer
Do not add individual comments that just restate what the code already tells you. For example, for the first assignment statement in Figure 8.1’s main method, this comment would be overkill:
s1 = new Student(); // instantiate a Student object
Developing readable programs is an important skill and a bit of an art form. Having too few comments is bad because it leads to programs that are difficult to understand. But having too many comments is also bad because it leads to cluttered programs that are difficult to wade through. There’s a similar balanc- ing act for blank lines. Having too few blank lines is bad because it leads to programs that are difficult to understand. But having too many blank lines is also bad because it leads to programs with too much dead space.
Blank Spaces
As shown in Figure 8.1 and Figures 8.2a and 8.2b, include blank spaces:
• after the single asterisks in the prologue
• before and after all operators (except for the operators inside a for loop header)
• between a closing brace and the //’s for its associated comment
• after the //’s for all comments
• after the if, while, and switch keywords
On the other hand, do not include blank spaces:
• betweenamethodcallanditsopeningparenthesis
• withineachofthethreecomponentsinaforloopheader
Direct reader to more info.