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

ables, for they generally serve a different purpose and do not have such a close
logical relationship.
Take care to write good explanations of fields, for they will help not only
other readers but you, as you develop the class.

Describing parameters
Each parameter of a method should be described in the specification of the
method, which appears just before the method as a comment. If a parameter is
not mentioned in the specification, the specification is incorrect.

Lesson
page 13-5

Describing local variables
Local variables are declared in the body of a method. The principles and
conventions that hold for commenting instance variables hold for local variables
as well. However, local variables are used in a much smaller context than
instance variables. Because of this, not all local variables need defining com-
ments. If a local variable is declared and then used only in the next line or two,
it probably does not need a definition. If a local variable is used throughout the
method, especially in loops, it needs a defining comment.
Use your judgment when deciding whether to place a comment next to the
declaration of a local variable. Will you be able to easily understand the mean-
ing of the variable from its use five weeks later if there is no comment? If not,
annotate the declaration with an explanatory comment.

Activity
13-5.2

The placement of local-variable declarations
The information-hiding policy says to hide information that is not needed at
a particular point so that a reader is not encumbered with unnecessary detail. This
policy, in relation to local variables, says to:

/** Permute w.x, w.y, w.z so that w.x <= w.y < w.z */
public static permute(Triple w) {
int tmp1;
int tmp2;
int tmp3;
// Swap the largest of w.x, w.y, w.z into w.z
if (w.x > w.z)
{ tmp1= w.x; w.x= w.z; w.z= tmp1; }

if (w.y > w.z)
{ tmp2= w.x; w.x= w.z; w.z= tmp2; }
// Swap the larger of w.x and w.y into w.y;
if (w.x. > w.y)
{ tmp3= w.x; w.x= w.y; w.y= tmp3; }

}
Figure 13.10 Putting local variables at the beginning of a method