Skip to content

Lab 9 – Debugging and Javadoc

Objective

  1. Practice working with code written by another developer.
  2. Practice debugging compiler errors, runtime errors, and logic errors. Many of these are common errors that students encounter in Project 1. My hope is that if you solve them here, they will be much easier to solve if you encounter them again in Project 1.
  3. Practice with an application consisting of multiple files to help prepare you for project 1.
  4. Practice writing proper javadoc style comments.

Program Design

Study the following class diagram and sequence diagram of the Trail Guide application. The purpose of this program is to load a CSV file and parse it for trail information. It then outputs the trails to the console.

Class Diagram

This class diagram was build using IntelliJ, so it looks a little different than the Project 1 Class Diagram.

UML class diagram for the Trail Guide application generated by IntelliJ, showing five classes. Trail has fields for city, state, length, and name, plus a constructor, getter and setter methods for each field, and a toString method. TrailBuilder has a trailList field (an ArrayList of Trail objects) and a TRAIL_FILE constant, plus methods for reading the CSV file and building Trail objects: readCSV, parseLineOfTrailInfo, createTrail, createTrailList, and addTrailToList. TrailReport has a trails field (an ArrayList of Trail objects) and methods getTrails, setTrails, and printTrailReport. Launcher has a constructor and a main method. TrailGuide has a constructor and a run method.

Trail Guide class summary

Class Responsibility
Trail Data object that holds information about one trail: name, city, state, and length.
TrailBuilder Reads the CSV file, parses each line, and builds a list of Trail objects.
TrailReport Holds the list of trails and prints them to the console.
Launcher Entry point. Contains the main method that starts the program.
TrailGuide Coordinates the program. Its run method connects TrailBuilder output to TrailReport for display.

Sequence Diagram

Whoa! What is this? A sequence diagram is a visual representation of the interactions and communication between objects within an application. It illustrates the chronological order of method calls between these objects, helping to visualize the flow of control and data. Sequence diagrams are valuable for designing, documenting, and understanding the behavior and interactions of different applications.

Use the below diagram to help visulize what is happening in the Trail Builder application. Maybe create a sequence diagram for your Analyzer project?

Sequence diagram for the Trail Guide application showing the order of method calls between five objects: Launcher, TrailGuide, TrailReport, TrailBuilder, and Trail. Launcher calls run() on TrailGuide. TrailGuide calls setTrails() on TrailReport, which calls getTrailList() on TrailBuilder. TrailBuilder enters a loop for each line in the CSV file: it calls readLine() to get the next line, calls parseLineOfTrailInfo(line) to break the line into fields and returns trailInfo, then calls createTrail(trailInfo) on a new Trail object and receives the trail back, then calls addTrailToList(trail) to store it. After the loop ends, TrailBuilder returns the completed trail list to TrailReport. Finally, TrailGuide calls printTrailReport() on TrailReport to display the results.

Trail Guide sequence summary

The sequence diagram shows the order in which objects talk to each other when the program runs:

  1. Launcher.main() creates a TrailGuide and calls run().
  2. TrailGuide.run() tells TrailReport to set its trails by calling setTrails().
  3. TrailReport asks TrailBuilder for the trail data by calling getTrailList().
  4. TrailBuilder enters a loop, processing each line of the CSV file:
  5. Reads one line with readLine().
  6. Parses the line into trail fields with parseLineOfTrailInfo(line).
  7. Creates a new Trail object with createTrail(trailInfo).
  8. Adds the trail to its list with addTrailToList(trail).
  9. After the loop, TrailBuilder returns the completed list of trails to TrailReport.
  10. TrailGuide then calls printTrailReport() on TrailReport to print all trails to the console.

Before You Start: Read the Debugging Strategy

This lab asks you to fix compiler, runtime, and logic errors. Before diving in, review the Debugging Strategy page for a step-by-step process that will help you work through errors efficiently and avoid common pitfalls.

Instructions

  1. Download the following classes and save them to your labs1 directory.

  2. Download the following file and save it in your projects directory.

  3. When working properly, this program should display the following output: Terminal output showing the result of running "./runLabs1.sh Launcher". The program prints four trails: Trail(name='Seeley Pass', city='Hayward', state='WI', length=8 miles), Trail(name='Seeley Hills', city='Hayward', state='WI', length=10 miles), Trail(name='Mt Ashwabay', city='Bayfield', state='WI', length=10 miles), and Trail(name='Camrock Park', city='Cambridge', state='WI', length=11 miles).

  4. Currently, the program has several bugs and it does not compile. Your first job is to fix the compiler errors. Work through these one at a time.

  5. After you fix the compiler errors, and you are able to run the program, you will discover some runtime errors. Your next job is to fix those!

  6. After you fix the runtime errors, carefully compare the program output to the screenshot above to make sure the output is correct. If it isn't, there are more bugs to find.

  7. When the program is working properly, it's time to focus on JavaDoc. To begin this portion of the lab, run ant jdoc, examine the warnings and errors, and resolve each one. The image below demonstrates a clean javadoc execution.

Terminal output showing the result of running "ant jdoc". The output lists javadoc tasks completing in sequence: Generating Javadoc, Javadoc execution, Loading source files, Constructing Javadoc information, Building trees and indexes. The final lines read "BUILD SUCCESSFUL" with a total time of 4 seconds, indicating no Javadoc errors or warnings.

  1. Once you acheive a clean javadoc execution, review the generated html documentation (it's in projects/docs) to make sure each class and method has well-formed, descriptive javadoc. If a comment is missing, add it. There are a five TODOs in the source code that will guide some of this work. You should answer the five TODO questions in your weekly reflection.

  2. When you are finished, verify there are not any errors or warnings related to these classes when running ant jdoc, and that your program still compiles and executes as expected.

Screenshots

To receive credit for this lab save screenshot(s) in the projects/screenshots/week4 directory.

You may combine the below into one screenshot and name it lab9.png.

  1. Add a fifth trail, named with your name, to trails.txt. If I were completing this, I might add: "Kari Schumacher,Madison,WI,17".
  2. lab9-output.png: The command line output showing all five trails.
  3. lab9-jdoc.png: The command line output when running ant jdoc

Submit Weekly Labs

  1. Add, commit, and push!
  2. Verify all work, including screenshots are visible in GitHub.
  3. Select 00 Weekly Labs Ready for Review.
  4. Enter the title: Week 4 Labs
  5. Answer the reflection questions in the space provided.
  6. Add the answers to each of the 5 TODO question in Lab 9.
  7. Click Create.

Rubric

All of the following must be satisfied to achieve a "Met" status

  • Screenshot should clearly show tests passing.
  • Screenshot should clearly show expected output when running the program (happy path).
  • Code and screenshots are properly named and saved in the correct directory.
  • All lab steps have been accurately and appropriately implemented.
  • Code adheres to the course coding standards.
  • Commit messages are concise, atomic, and effectively describe the change(s) made.
  • JavaDoc documentation is properly implemented, providing clarity and understanding of the code's functionality and usage.
  • External sources (websites, classmates, AI tools, etc), if utilized, are referenced and documented within the code as comments.

Additional Considerations

  • Issue created correctly with thoughtful answers to the reflection questions.
  • JavaDoc questions answered correctly in the issue (5 TODO questions in the code).
  • Screenshot shows Ant jdoc executed with no errors.