Java Reference
In-Depth Information
at this, we can also see that the doc comments for the getTeam() method don't correspond to
the signature of the method itself; it looks like this was left over from an earlier design of the
interface that would have identified Team objects by their String names.
Nor is there any discussion of the requirements on the various methods. For example, the ex-
isting documentation tells us that the UUID returned by the getId() method is used to dif-
ferentiate between players who might have the same name. From this we can conclude that
different players should have different IDs, but what is the scope of the difference? Should all
players have different IDs, or is it only important that players with the same name have differ-
ent IDs? This sort of thing might be obvious to the designer of the interface, but for those who
are going to use the interface, it might not be so obvious.
Finally, the Position enumeration we have defined inside of the Player interface has no doc-
umentation at all. Given that our expanded summary of the interface tells us that the other in-
terfaces for the statistics package that will be implemented by an object representing a player
will depend on the value of the Position field for the player, it is important that we document
this enumeration. Indeed, as part of that documentation, we might point out that the position
of DH can be assigned only to Player objects that are on a Team in the American League, at
which point we will realize that we have no information on which league a Team is part of in
the Team interface. By doing the documentation right, we have found a flaw in our design that
we can repair before writing the code.
And what about our claim in the summary that an object implementing the Player interface
can be used to get the various forms of statistics for the player? How does the interface allow
this to happen? Maybe we are assuming that objects that implement the Player interface will
also implement the other statistical interfaces. But in fact (and for reasons that will be dis-
cussed later) we have in mind a design that will let an object implementing the statistical inter-
faces be obtained from an object that implements the Player interface. But there is no method
that would allow this, so we'd better add one. Writing the documentation not only let us find
a flaw in our design, it also allowed us to see where our design was incomplete.
If we make all of these changes, then the result looks more like:
package org.oreilly.javaGoodParts.examples.statistics;
import java.util.UUID;
* Basic interface for a player object. An object implementing
* this interface can be made part of a {@link Team}. Classes
Search WWH ::

Custom Search