Documentation and Critique of a Program
The objectives of this laboratory are:
- To give you practice in documentation systems with UML class and sequence diagrams;
- To introduce you to the javadoc documentation; and
- To give you an opportunity to consider a better way to structure a small program as a system of packages, classes, attributes and methods.
You must submit your laboratory report and source code by e-mail to
- Your two model files in VP-UML;
- A .zip file containing your source code with comments, exported according to instructions in the Eclipse survival guide; and
- A concise laboratory report, in the laboratory format, as a PDF file, which contains:
- A brief discussion;
- A copy of all the diagrams created, exported your diagrams following the method explained in laboratory 0; and
- Your answers to the questions.
The discussion must be about what you have learned, the discoveries you made, what was difficult in the laboratory, but not a list of steps followed or empty phrases about the importance of this lab. Be concise! A good discussion paragraph is better than 10 filling pages.
The UML language can be used as a documentation language: that is, to document the design of a system that already exists. A good choice of UML diagrams can facilitate understanding of the structure and behavior of a system. We will use UML as a documentation language in this laboratory; Next week we will use it as a design language.
The javadoc is a system to create documentation for programs that is navigable with a web browser. If you used the Java 8 API documentation, you have seen javadoc. In this lab you will learn how to write and generate your own javadoc.
Documenting a system with the UML language can help us understand the advantages and disadvantages of its design. In this laboratory we give you two designs of a system and ask you to compare various aspects.
Download file lab2bouncy-a.zip. Create an Eclipse project and import the file. Run the
BouncyApp class to verify that the import has worked. Detailed instructions for importing a file are in the lab 1 instruction.
Do the same with the lab2bouncy-b.zip file in another Eclipse project.
Both versions of the Bouncy system have identical definitions of the
Vector2D classes and they have exactly the same behavior. The colored balls bounce and you can destroy them by clicking on them. If you destroy all the balls, the bottom of the screen becomes dark gray. Nothing more.
Part 1 – Class diagrams
Create one class diagram for each version of the Bouncy system. Since there are classes in both systems with the same fully qualified names (e.g.,
bouncy.Ball) you will need a separate Visual Paradigm project for each version.
You may create the class diagrams manually using Visual Paradigm’s drawing features, or you may use Visual Paradigm’s “Instant Reverse” feature. Do not use the “Java Round-trip” feature.
If you use Instant Reverse you will still need to compare your diagrams to your code, add missing elements, and lay things out intelligently: Instant Reverse will not find all the relevant details in your code and will omit some of the entities and relationships required below.
Lay out your diagrams to make it as easy as possible to understand the systems you are documenting.
Your diagrams must show:
all classes in the
full details of all non-static attributes and methods (you may show static members but you do not need to); and
the package to which each class belongs;
all relationships between classes in the
vector2dpackages, including dependencies, with full details of the relationships;
all generalization (inheritance) and realization (interface implementation) relationships between classes in the
vector2dpackages and classes in the Java standard libraries. For the Java standard library classes and interfaces you must show the packages to which they belong but you need not show any attribute and method details (though you may if you wish).
For version “b” of BouncyApp, you must also show the relationship between the
java.util.Observerinterface and the
Part 2 – Sequence diagram
Create a complete sequence diagram showing all method invocations and object creations that result from invoking the method
movingAwayFrom(Ball other) found in the class
Ball. If a method invocation causes other methods to be invoked, you must show the entire invocation chain.
Do not use Instant Reverse to draw this diagram; it gets things wrong and you won’t learn anything in the process. Draw the diagram manually using Visual Paradigm’s tools. It’s a very good idea to do a rough version on paper first.
Part 3 – Javadoc
Complete the javadoc comments for the class
BoucyApp in version “a” of the Bouncy system and the classes
BouncyView in version “b” of the Bouncy system. Comments have been provided for the
Vector2D classes; use these as examples of what is expected. The Wikipedia article on javadoc provides a concise explanation. Oracle's official documentation on How to Write Doc Comments for the Javadoc Tool provides a more complete reference, if you need more detail.
Be sure to add your names to the author comment in each class.
javadoc is intended to be read in a web browser after it has been generated. Generate the javadoc for your project including all members with visibility of private or higher (which is all members). See the Project menu in Eclipse for the appropriate command.
Check the messages in the Eclipse console for any errors and fix them. Review your javadoc in a web browser, starting from the
index.html file. If your documentation isn’t clear, is missing something, or doesn’t read well, fix it. Repeat the process until you are satisfied that your javadoc adequately documents the system.
Part 4 – Questions
Vector2D class is in a separate package from the rest of the system. Is this appropriate? Why or why not?
2. There are two methods called
Vector2D. The technical name for this is method overloading.
a. Why is the
plusis invoked in client code, how does the system decide which method to execute?
y have public visibility. An alternate approach would be to make them private and provide
getY methods. Discuss the advantages and disadvantages of these two approaches. In your discussion, consider how
Vector2D is used by the
Ball class and assume this is typical.
4. Compare the
makeBalls method in the version “a”
BouncyApp class with the
makeBalls method in the version “b”
a. Are the
hueFromDiametermethods in the
BounceSimulatorversion worth the effort of defining them and the complexity they add to the class?
b. Why or why not?
5. Compare the declared visibilities of the two
makeBalls methods from question 4. Which visibility is most appropriate? Would some other visibility level be better? Justify your answer.
6. Compare the structure of the event listeners in the version “a”
BouncyApp class with the structure of event listeners in the version “b”
BounceSimulator classes. (That is, what objects are listening for what events.) You can find the places listeners get attached by looking for invocations of
7. The version “a”
BouncyApp class implements the
java.awt.event.MouseListener interface. The
BallKiller inner class of
MouseListener, instead of extending
MouseAdapter, what would have to change about its structure?
b. In your own words, briefly explain the purpose of the
c. Version “a”
MouseAdapter. Why not?
8. Compare the overall structures of versions “a” and “b” of the Bouncy system. In your own judgement, which system is better from the point of view of each of the following? Justify your answers for each, with reference to the design principles discussed in class. Be specific about what aspects of the systems cause you to answer as you do.
a. overall simplicity;
b. ease of understanding;
c. ease of modification or extension;
d. ease of reuse of parts of the system in other contexts.