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

Reading the program segment in this way, we get a first, abstract view of what it
does, and if this our concern at the moment, we need read no further. If our con-
cern is how the permutation of x , y , and z is done, we can read the indented code
underneath it, for the moment putting the first statement and second statement
out of our mind:

// Permute x , y , z so that x<=y<=x
// Swap the largest of x , y , z into z
// Swap the larger of x , y into y
Thus, the permutation is done in two steps. To see how the second statement is
implemented, read the indented code underneath it (see Fig. 13.6).
The use of statement-comments in this program provides us with three lev-
els of abstraction, allowing us to read the program in three different ways. We
can focus our attention on whatever concerns us at the moment.

Indentation guidelines for statement-comments and their implementations
Figure 13.6 illustrates one of our two ways of indenting statement-com-
ments and their implementation:

1. The statement-comment itself is indented the same amount as the other
statements in the sequence.
2. The implementation of a statement comment is indented four spaces
underneath it.

This method of indentation is preferred because it most clearly shows the struc-
ture of the program. However, the field has not adopted this method. Instead,
they generally use the following conventions, as illustrated in Fig. 13.7.

1. The statement-comment itself is indented the same amount as the other
statements in the sequence.

First statement ;
// Permute x , y , z so that x<=y<=x
// Swap the largest of x , y , z into z
if (x > z)
{ int tmp1= x; x= z; z= tmp1; }
if (y > z)
{ int tmp2= y; y= z; z= tmp2; }

// Swap the larger of x , y into y
if (x > y)
{ int tmp3= x; x= y; y= tmp3; }

Second statement ;
Figure 13.7: Alternative indentation for statement-comments