Project Deliverable 0: Understanding the Code Base

Objective: Exploring the Code Base

There is so much code! You need to find ways to help you understand what is happening. It's an iterative process. Here are some ideas to get you started. This isn't an ordered list. You'll start at different points, and it will take you in various directions. Each time you start again, you're adding to your mental model.

Find Your Foothold

View the application in your browser. It's helpful for you to go back and forth between the code and the application to see how the pieces fit together.

You need to find a way to get started. Often, once you find a place to get started, you can build from there. Here are some approaches you can try. They are not mutually exclusive, and you'll come back to them as you learn the code.

• Look at the directory structure or look for file names that you think you know what they would do (e.g., index or login).
• Search the files in the repository for terms that you expect to be part of the application because of the domain. This could give you way more results than you want, but it could be a good starting point. You don't have to go through all of them necessarily.
• Search the files in the repository for key words or phrases from the running web application to find out where they show up in the code
• Skim comments and contents to get the "jist" of the file. Consider: what part of MVC does it seem to be? You don't need to look at the file in depth at this point. You're looking for clues, like what is the file's extension? What is in the file, e.g., is it Java code--logic or JDBC? HTML?)

You'll likely need to repeat this process a few times as you begin to understand the structure of the code.

Learn the Application's Terminology

Based on your earlier exploration of the web application as a user, what are the "things" in this application? Are there different types of users? What objects are users working with? For example, for a site like PetFinder, there are users from the shelter and users looking for pets. The objects that they are working with are the pets, shelters, and adoptions.

Where do those terms show up in the code base?

Learn the Framework's Terminology

If there is a word/term that comes up a few times in the names of files/methods/packages that you don't know, look it up in context of the framework that is being used.

Following a Use Case

Once you find a foothold, follow it out/through--to the beginning and to the end for a user. This may require some searches of the repository. Work your way out--how did the request get here? Where would the request go from here? Repeat that process until you start where the user would and end with the response back to the user. Then, follow the path from start to end, making sure you don't miss anything. Now you're getting some depth of understanding.

Objective: Documentation for the Project

Create a file in whatever format you want (Markdown, plain-text, Word, Google Sheets, ...) to document the project, as described below.

Document Technologies

Create a list of the frameworks/technologies used in the application. For example,

• What framework is the web application built in?
• What are the technologies/languages used: Java (servlets, JSPs), JavaScript, ...?
• What libraries are being used? These could be Java, JavaScript, ...
• What other components are used? Databases, data stores, ...

Document the Directories

List the major directories and label their role in the application. You don't need to list all the directories. Often, there is a parent directory, which you can label and then say a bit about what's inside its subdirectories.

Document the Configuration Files

What are the configuration files? Where are they located? What can you configure?

Document the Flow for One Use Case

For one common use case, document the flow of the request and the response, talking about the actors/components involved. Something like, "The user is on the login page, enters their username and password and hits the login button. The request generated is to the /Login, which is handled by the LoginServlet. In the LoginServlet, the database is queried by class A. Classes B and C do X and Y. The request is forwarded to J, which displays Z to the user."

Document the Architecture

The last part was a pretty low-level look at the application. This is supposed to be a high-level look at the application. Create a picture, similar to what we've seen in class, but for your application. Label the components and how they interact. If components communicate with each other, use an arrow between them to indicate that communication.

Grading (20)

Due by Sunday at 11:59 p.m.

Graded by completion -- on Monday, I'll go around the room, and you show me the document you created.