Programming and Problem Solving with Java

694

Even if comments aren’t needed, blank lines can be inserted wherever there is a logical break

in the code that you would like to emphasize.

Sidebar commentsappear to the right of executable statements and are used to shed light

on the purpose of the statement. Sidebar comments are often just pseudocode statements

from your responsibility algorithms. If a complicated Java statement requires some expla-

nations, the pseudocode statement should be written to its right. For example:

while((line = dataFile.readLine()) != null)// Get a line if not EOF

Because the page of a textbook has a fixed width, it is sometimes difficult to fit a sidebar com-

ment next to a long line of code. In those cases, we place the sidebar comment before the

statement to which it refers. Most computer screens can now display more characters on a

line than fit across a page, so this situation is less common in practice. However, if lines of

code become too long, they are hard to read. It is then better to place the sidebar comment

before the line of code.

In addition to the four main types of comments that we have discussed, there are some

miscellaneous comments that we should mention. Although we do not do this in the text,

to conserve space, we recommend that classes and methods be separated in a compilation

unit file by a row of asterisks.

//*********************************************************************

Programmers also sometimes place a comment after the right brace of a block to indicate

which control structure the block belongs to. This is especially helpful in a package file where

there may be multiple classes. Indicating where a class or long method ends helps readers

keep track of where they are looking in scanning the code.

returnnoCorrect;

}

} // End of class TheKey

Identifiers

The most important consideration in choosing a name for a field or method is that the name

convey as much information as possible about what the field is or what the method does.

The name should also be readable in the context in which it is used. For example, the following

names convey the same information, but one is more readable than the other:

datOfInvc invoiceDate

Although an identifier may be a series of words, very long identifiers can become quite te-

dious and can make the program harder to read. The best approach to designing an identi-

fier is to try writing out different names until you reach an acceptable compromise—and then

write an especially informative declaration comment next to the declaration.