OOGASalad : Design Plan

You can scarcely compress the time it takes to do good design. The best you can do is arrange the process so that progress is conspicuous and the partially-completed result has its own intrinsic value. — Dorian Taylor

This part is intended for your team to agree on the project's organization, priorities, and the primary APIs and frameworks that will drive your design. Develop your ideas in enough detail to convincingly describe your APIs (primary public classes and their public/protected methods) that will work together to provide the project's functionality, without committing to actual implementation details.

It also helps to help make sure everyone on the team starts with a similar understanding.

If you are having trouble thinking of how to design games flexibly, try playing either the card game Fluxx or the video game Baba is You, both of which allow the player to dynamically change the rules and goals during the game.

Submitting your Work

Individually, each student must acknowledge their intent to participate in this team project by "signing" their team's specific Team Contract.

Use GIT to push your team's plan to the master branch of the provided, shared, oogasalad_TEAM repository hosted in the course's Gitlab group as your team's submission of this part of the project, using the

• doc folder: files that go beyond initial planning because they are intended to be living documents that are updated throughout the project
• doc/plan folder: the plan Markdown files as well as any direct supporting documents (UML diagrams, CRC images/scans, etc.)
• doc/plan/wireframe folder: images or other files showing the user interface
• doc/plan/api folder: Java interface code files detailing your APIs (these should compile)
• doc/plan/usecases folder: Java code files detailing how to use your APIs (these do not need to compile and definitely are not expected to run)
• doc/plan/data folder: basic data file(s) needed to represent an example game

No running code is required for this submission (just examples).

Specification

Create a folder within the doc folder, called plan, that contains the following files associated with your initial design plan:

• Team Contract (doc/CONTRACT.md)
  Based on your experience with teams in this course, create your own Team Contract for this project that describes your team work goals and responsibilities (and is "signed" by everyone). Make sure to include these topics: communication goals, identifying the quality of work everyone wishes to achieve, the level of group participation and individual accountability everyone feels comfortable with, how to make the team a safe place for everyone to participate, and meeting frequency. When making your contract, consider the following resources:
  • minimal contract used for previous projects
  • guidelines for writing a Team Contract
  • Codes of Conduct examples for Open Source projects
  • course's individual expectations for team projects
• Use cases (doc/BACKLOG.md)
  Write at least six Use Cases per team member that describe specific features each person expects to complete — these will serve as the project's initial Backlog. Focus on features you plan to complete during the first two Sprints (i.e., the project's highest priority features). Note, they can be similar to those given in the assignment specification, but should include more detail specific to your project's goals. It may help to draw a diagram of how your classes collaborate or even role play the objects for each case.
• Example games (doc/plan/EXAMPLE_GAMES.md)
  Describe in detail at least three example games from your genre or game variations that differ significantly in their functionality. These example games should help clarify the abstractions you plan to use in your design, so explain why you chose them and clearly identify their functional commonalities and differences. Note, they do not need to be the final ones you implement but certainly could be.
• User Interface Wireframe (doc/plan/wireframe)
  Create one or more pictures of the user interface to serve as a wireframe of your GUI(s), a prototype that can be shared, commented on, and easily updated. Provide enough detail to show basic interactions and at least five erroneous situations that are reported to the user (i.e., bad input data, empty data, etc.). You are encouraged to use a modern drag and drop layout tool for web or desktop apps (such as Figma or PowerPoint), ExcaliDraw (a Markdown-oriented drawing tool!) or you can scan in hand drawn, annotated, pictures.
  
• Design (doc/plan/DESIGN_PLAN.md)
  Write your design goals (i.e., what is encapsulated and what is flexible), and the design's primary architecture (i.e., what is closed and what is open) without committing to any concrete implementation (i.e., do not reference specific standard Java classes, data structures, or code). This should emphasize the abstractions you will create to capture your game or genre's key commonalities and differences. Describe how your intended design will handle your team's goals for the project's basic and extended functionality using APIs to provide services. For each API you plan to build, provide a roughly "one page" high-level design overview using the format below. Include a picture of how the modules are related (these pictures can be hand drawn and scanned, saved from an online CRC card tool, written in Markdown, created with a standard drawing program, or screen shots from a UML design program).
  
• APIs (doc/plan/api)
  Write at least one API Design Overview per team member that describe the API's design goals, primary abstractions and their behavior, as well as how they serve developers and collaborate together regarding the overall project design's key goals and principles.
  
• API Examples (doc/plan/usecases)
  Pick at least five Use Cases and provide example "implementations" using only methods declared in your API interfaces. Note, these should be Java code files that contain extensive comments explaining how you expect your different APIs to collaborate. You can implement each use case either in a single class to show how the steps are connected "procedurally" or in separate classes (that implement the appropriate interfaces) to show how the steps are "distributed" across the objects as appropriate. In either case, make it clear which how the implementation relates to the Use Case. You will likely need to create simple "mocked up" objects that implement your interfaces so you have something concrete to create, using new, and call methods on.
• Example data (doc/plan/data)
  Write example data file(s) to represent a simple game. Their goal is to help the team agree on standard locations and formats for your shared data (such as property files for configurations within your Java code, your team's chosen file format for representing game data, and other asset files like HTML pages, images, or sounds) rather than to create a complex working game. Note, your example does not need to be exhaustive, just representative of the file's format.
• Test Plan (doc/TEST_PLAN.md)
  Describe at least two specific strategies your team discussed to make your APIs more easily testable (such as useful parameters and return values, using smaller classes or methods, throwing Exceptions, etc.). Describe at least three test scenarios per team member for a project feature they plan to be responsible for (at least one of which is negative/sad/error producing), the expected outcome, and how your design supports testing for it (such as methods you can call, specific values you can use as parameters and return values to check, specific expected UI displays or changes that could be checked, etc.). A test scenario describes the expected results from a user's action to initiate a feature in your program (whether "happy" or "sad") and the steps that lead to that result.
• Implementation Plan (doc/SPRINT_MILESTONES.md)
  Describe your plan for how to manage and prioritize the project, including a rough timeline what you expect to complete for each deadline, the extension feature(s) you want to include, and which APIs each team member plans to take primary and secondary responsibility for. Specifically, each person should take responsibility for specific features and Use Cases they intend to work on during each Sprint (i.e., each week). This requires the team to agree on the feature priorities and set goals for what to complete for each deliverable.

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

Frameworks

In everything, focus on how to build a variety of games in your genre. Explain the key features in your game genre, how you will support those features, and how you expect new games to be written (i.e., what needs to be sub-classed, what accepts Lambdas, what is configured by files, and how communication will occur between the Authoring Environment, Engine, Data, and Player).

Some of your APIs will likely be organized as frameworks, i.e., code that provides the control flow into which future developers (teammates) must fit their code based on provided extension, or plugin, points (i.e., compare the OpenJFX framework to Java's Collection classes). Thus it is vital that you describe these extension points in English with examples beyond simply listing classes and methods you expect to implement. For example, there are many ways to think about a game (such as a series of events, different states, all possible collisions, levels of rules, smart actors, plans, etc) and your choices could impact everything, up to and including the GUI presented to a game designer.

Ultimately, you goal should be to explain how to use your APIs (and frameworks) to actually construct specific games.

API Design Overview

An Application Programming Interface, API, is simply all of the program's public classes and methods. Thinking about the public methods together as an interface to your program or service to other innovative programmers has the power to change how you perceive those methods from just something necessary to make the program functional to providing a service to other programmers (even those on your own team!). An API, then, essentially becomes a contract and developers, now clients, are enticed to use the API because they know they can rely on 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 components dependent on them.

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

• Easy to learn
• Hard to misuse
• Provide for extension

Writing both English and Java descriptions of how to solve a concrete task using your API can be very helpful to validate the desirable characteristics above from different perspectives:

• English: what are your design goals and how do you want programmers to think about accomplish a task with your API using metaphors or analogies (e.g., folder or state machine paradigm)
• Java: what standard programming ideas (e.g., step by step or substitution via polymorphism) are going to be used and what actual Java classes and methods make up the API to accomplish a task

Describe and justify your reasoning for the design of each in the following sections:

• Overview. Describe the API's design goals, how it provides for extension, while upholding SOLID Principles and the Pillars of Object-Oriented Design, to create a more expressive and flexible experience for other developers that encourages them to create new features.
• Classes. Write any number of Java interface types in appropriate packages, to represent your APIs. These must be Java code files that compile and contain extensive comments to explain the purpose of each interface and each declared method (this basic code can be generated directly from a UML diagram or used to create a diagram). Include any Exceptions you plan to throw because of errors that might occur within these methods.
  Note, this does not require that all of these types will remain as interfaces in the final implementation, just that the goal is for you to focus on each type's behavior and purpose rather than its state.
  Note, classes may be shared by multiple APIs and their role should be described separately in each.
• Example. Start coding with your API immediately by providing an example of how to solve one or more concrete tasks.
• Details. Describe the API handles specific features given in the assignment specification, what resources it might use, how it collaborates with other APIs, and how it could be extended to include additional requirements (from the assignment specification or discussed by your team). Some APIs will be called by other APIs, but some will represent frameworks. Thus it is important that you describe the plugin points in English and provide examples of their use in order to make it clear how to use the API to actually construct a specific game features.
  
• Considerations. Describe any issues which need to be addressed or resolved before attempting to devise a complete design solution. Include any design decisions discussed at length (include pros and cons from all sides of the discussion) as well as any ambiguities, assumptions, or dependencies that might impact the overall program.

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/api or doc/plan/usecases folder when you are satisfied they are complete.

Resources

• Bumper-Sticker API Design by Joshua Bloch from his presentation How to Design a Good API and Why it Matters
• Understanding the API-First Approach to Building Products from swagger.io (promoting API Development for Everyone)
• Use Case Checklist from Writing Effective Use Cases by Alistair Cockburn (pronounced [Co-burn] the Scottish way)
• You Are Not Done Yet Testing Checklist by Michael Hunter