Implementing Classes - Java Concepts - page 122

And here is a program segment that adds interest to a savings account:

double interestRate = 5; // 5% interest
double interestAmount
= momsSavings.getBalance() * interestRate /
100;
momsSavings.deposit(interestAmount);

89
90

As you can see, programmers can use objects of the BankAccount class to carry
out meaningful tasks, without knowing how the BankAccount objects store their
data or how the BankAccount methods do their work.

Of course, as implementors of the BankAccount class, we will need to supply the
internal details. We will do so in Section 3.5 . First, however, an important step
remains: documenting the public interface. That is the topic of the next section.

S ELF C HECK

3. How can you use the methods of the public interface to empty the
harrys-Checking bank account?

4. Suppose you want a more powerful bank account abstraction that keeps
track of an account number in addition to the balance. How would you
change the public interface to accommodate this enhancement?

3.3 Commenting the Public Interface

When you implement classes and methods, you should get into the habit of
thoroughly commenting their behaviors. In Java there is a very useful standard form
for documentation comments. If you use this form in your classes, a program called
javadoc can automatically generate a neat set of HTML pages that describe them.
(See Productivity Hint 3.1 for a description of this utility.)

A documentation comment is placed before the class or method definition that is
being documented. It starts with a /** , a special comment delimiter used by the
javadoc utility. Then you describe the method's purpose. Then, for each method
parameter, you supply a line that starts with @param , followed by the parameter
name and a short explanation. Finally, you supply a line that starts with @return ,