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

"there is no longer peace" , the programmer expects this statement to store
3 in vowelNumber . But it does not; it stores 2 . An error has been introduced into
the program.
Such scenarios happen too often in programming. They lead to a great deal
of lost time and cause immense frustration. There are at least two ways to guard
against them.

1. One way is not to use method specifications at all. But this wastes a great deal
of time because it forces the programmer to look at and understand the body of
a method whenever a call to the method is to be written.

2. A second way to guard against these kinds of scenarios is simply to keep
method specification and body consistent. This is a far better way to prevent
these kinds of errors. It is best done by changing the specification first and then
changing the body to fit it.

13.3.3 Using statement-comments

When reading or writing a program, we have many concerns, and we have to
focus our attention on one at a time. The more structure that is evident in a pro-
gram, the easier it is to separate our concerns and deal with one at a time.
A comment that acts as a statement —an instruction to do something—can
be useful in providing structure. We call such a comment a statement-comment .
The statement-comment says what to do; the code indented underneath it says
how to do it. (Later, we discuss indentation with respect to statement-comments.)
Using statement comments, Fig. 13.6 is viewed as a sequence of three state-
ments:

Lesson
page 13-4

Activities 13-4.3
- 13-4.5 are easi-
er to understand! First statement ;

// Permute x , y , z so that x<=y<=x
Second statement ;

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.6: Using statement-comments