Java Reference
In-Depth Information
Javadoc specifications
A method specification or class specification that is commented using the
delimiters
/**
and
*/
(yes, the opening delimiter has two asterisks) is called a
Javadoc comment
. The program Javadoc can be used to extract all Javadoc com-
ments from a program and put them in an html format so that one then has a
specification document. The Java API class specifications were extracted in this
fashion. Appendix II.2 discusses Javadoc, and Sec. 2.3 of Appendix I shows how
to create a Javadoc specification in DrJava.
13.3.2
Keeping body and spec consistent
Consider the method in Fig. 13.4. Part of the body is written in English. Assume
the code for this statement has been written; we just do not display it here:
As an example, a call to
firstVowel
with argument
"peace"
yields the
value
2
because the first vowel,
"e"
, is character number 2.
Suppose that, during development of the program for which this method was
itself developed, the programmer decides that it would be better for the method
to produce the
index
of the first vowel, which is
1
, and not
2
. So the program is
changed as shown in Fig. 13.5. But the programmer does not change the speci-
fication of the function. They are in a hurry to complete the program, and they
think that they will fix the specification later, after the program is working. So
the specification and body are now inconsistent.
A few weeks later, while continuing to develop the program, the program-
mer writes a call to this function:
vowelNumber= firstVowel(b);
Having forgotten that the specification and body are inconsistent, the program-
mer has used the specification in writing the call. Thus, if variable
b
contains
/** =
no. of chars. in
b
up to and including the first vowel (
b
is known to contain a vowel)
*/
public static int
firstVowel(String b) {
int
r;
Store in
r
the no. of characters in
b
up to and including the first vowel of
b;
return
r;
}
Program 13.4:
Method firstVowel
/** =
no. of chars. in
b
up to and including the first vowel
(b
is known to contain a vowel)
*/
public static int
firstVowel(String b) {
int
r;
Store in
r
the index of the first vowel of
b;
return
r;
}
Program 13.5
Method firstVowel, with a modified body
Search WWH ::
Custom Search