Documentation and Critique of a Program

Objectives

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.

Submission

You must submit your laboratory report and source code by e-mail to This email address is being protected from spambots. You need JavaScript enabled to view it. before the next laboratory begins (i.e., before 14h30 on February 1st, 2017). Please submit:

  • 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.

Introduction

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.

Preparation

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 Ball and 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 bouncy and vector2d packages with

    • 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 bouncy and vector2d packages, including dependencies, with full details of the relationships;

  • all generalization (inheritance) and realization (interface implementation) relationships between classes in the bouncy and vector2d packages 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.Observer interface and the java.util.Observable class.

Part 2 – Sequence diagram

Create a complete sequence diagram showing all method invocations and object creations that result from invoking the methodmovingAwayFrom(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 BoucyApp, BounceSimulator, and BouncyView in version “b” of the Bouncy system. Comments have been provided for the Ball and 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

1. The 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 plus in Vector2D. The technical name for this is method overloading.

a. Why is the plus method overloaded?

b. When plus is invoked in client code, how does the system decide which method to execute?

3. Vector2D’s attributes x and y have public visibility. An alternate approach would be to make them private and provide setX, getX, setY and 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” BounceSimulator class.

a. Are the randomSize, randomVelocityComponent, randomPositionComponent and hueFromDiameter methods in the BounceSimulator version 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” BouncyView and BounceSimulator classes. (That is, what objects are listening for what events.) You can find the places listeners get attached by looking for invocations of addActionListener and addMouseListener.

7. The version “a” BouncyApp class implements the java.awt.event.MouseListener interface. The BallKiller inner class of BouncyView extends java.awt.event.MouseAdapter.

a. If BallKiller implemented MouseListener, instead of extending MouseAdapter, what would have to change about its structure?

b. In your own words, briefly explain the purpose of the MouseAdapter class.

c. Version “a” BouncyApp can’t extend 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.