CompSci 308
Spring 2024
Advanced Software Design and Implementation

SLogo : Design Plan

If you don't understand both sides of an issue, you cannot make an intelligent choice; in fact, if you don't understand all the ramifications of your actions, you're not designing at all. You're stumbling in the dark. — Allen Holub

This part is intended to get you to try to think about the design of a program in terms of APIs, i.e., the primary public classes and their public methods, and how they can actively support new functionality without changing and without revealing implementation details.

Take this time to get everyone on the team to start with a similar understanding.

No running code is required for this submission.

Specification

Describe the primary abstractions and classes that are needed to represent the program's basic functionality. Focus your design on how to represent a model in a extensible way and specifically on what behavior (i.e., methods) your classes would have instead of focusing on the instance variables. If describing an abstraction (i.e., an inheritance hierarchy), clearly identify what behaviors the classes have in common (i.e., the superclass/interface), and what are different, (i.e., the subclasses).

In the folder doc/plan, complete the DESIGN_PLAN.md document, including any direct supporting documents (UML diagrams, CRC images/scans, etc.), with the following sections:

This plan is not intended to be completely binding, but significant changes will be penalized. This is not meant to over-stress this process or squash your later creativity, just to note that if you end up throwing out the plan completely, then it is not clear you thought about the project in enough detail to make basic critical choices. Any changes to this plan should be addressed in your final DESIGN document (adding descriptive comments while you write the code for it can be helpful for remembering your thought process and other details about the change so you can explain it later).

APIs

An Application Programming Interface, API, is simply all of the program's public classes and methods. Thinking about public methods as a service has the power to change your purpose: from simply programming to finish functionality to providing a means to help other programmers innovate (even those on your own team!). An API then, is essentially a contract with developers, now clients, who are enticed to use the API because they know they can rely on the stability of that contract (even if the underlying implementation changes). Thus, many see API design as the most critical part of designing a program, because it affects the design of other dependent components.

Although the concept is inherently subjective, most developers seem to agree that APIs should have the following characteristics and need to be revised iteratively before getting them right:

In the folder doc/plan/api, write both English and Java descriptions of your APIs that represent different perspectives:

There are two primary subsystems: the backend (Model) and the frontend (View and optional Controller) (see DESIGN-09). The frontend should only access the Model through a well-defined public API composed primarily of Java interfaces and a limited number of concrete immutable types (defined in the slogo.model.api package, see: DESIGN-17). Along side of this (external) API for the Model, you will have an internal design for how the Model is extended to support new features. You will also have an internal design of the frontend to support extension, for a total of 1 External and 2 Internal APIs.

Make sure your API design addresses the following questions:

Note, classes and methods are commonly shared between these APIs and should be documented completely in just one (typically the External API) and then referenced in the other (typically the Internal API). If the context or contract changes based on how it is to be used, that will need to be clearly documented and justified. Most APIs are documented using a standard technique like Javadoc to automatically generate nice looking documentation. For this project, since you are just starting the process of thinking about APIs, we are not requiring a standard style of documentation.

Ideally, the API agreed to between the sub-groups should not be changed after this document because it affects how the other's part might work.

User Interface

Create a wireframe of your GUI(s) to serve as a prototype that can be shared, commented on, and easily updated. Show how the user will interact with your program (keep it simple to start). Include at least four pictures of the user interacting with the IDE and describe what is happening in each. Also show at least two erroneous situations and how they are reported to the user (i.e., bad input data, empty data, etc.).

In the folder doc/plan/wireframe, include pictures that can be hand drawn and scanned in, created with a standard drawing program (such as Figma or PowerPoint), ExcaliDraw (a Markdown-oriented drawing tool!), or screen shots from a dummy program that serves as a exemplar.

Use Cases

Use Case scenarios help test the completeness of your design. By writing the steps needed to complete a Use Case, you will see how effectively your design handles it and we will be able to better understand how deeply you have considered the basic issues. It may help to role play or draw a diagram of how your classes collaborate to complete each.

In the folder doc/plan/usecases, include Java code that compiles to represent the calls to public or protected methods described in your Java interfaces needed to complete each Use Cases. To simplify, you can code the steps for each in a single method with extensive comments to show in which class and method you think each line of code might ultimately be run. You do not have to implement any of the methods called.

Start with these Use Cases:

Then, each person on the team must write at least four Use Cases, one of which represents an erroneous scenario, focused on the project part they intend to take responsibility for. Each Use Case should reference a specific Functionality Requirement, but include more concrete details specific to the scenario.

Note, because your code examples should compile, you will likely want to write them in the src folder, then copy (or move) them into the doc/plan/usecases folder when you are satisfied they are complete.

Resources