Lab Team Meeting: Preparing for SLogo

In this lab, you will practice designing APIs, the public classes and their public 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.

In your SLogo teams, complete the following steps:

1. Introduce yourselves by sharing:
• your background and how you are doing in general this semester
• your motivation/interest in this course
• your knowledge/interest in other programming languages (especially Logo, Alice, Scratch, Lisp, or something similar) and APIs
• areas of the project you interested/concerned about
2. Discuss each person's team experiences and expectations:
   • share good and bad past team experiences and what you learned from them
   • share preferences and styles regarding expectations, communication, and debating/conflict
   • go over the Team Contract (which you will submit individually)
   • choose a time for the next team meeting
3. Practice thinking critically about API design
4. Practice designing APIs
5. Project API design
6. Plan your project

For shared Markdown editing, you can work

• directly within IntelliJ using the Code With Me feature
• online using this web-based, shared, editor (sign-in required)
• online using this web-based editor that can be plugged into Google Docs (regular synchronization required)

The result of this lab will be a set of documents that captures the important points of your team's several directed discussions.

Practice Thinking Critically about API Design

Complete this exercise to examine Java's Collections API from a design perspective (instead of as a user) to compare your experiences with its documented goals and motivations.

Before Moving On: Add your names and summary of your critical discussion to the file doc/COLLECTION_API.md, then add, commit the file, and push it to your shared slogo_teamNN repository.

Practice Designing APIs: Cell Society

In many projects, APIs serve two different goals based on the clients (other programmers): consumers that use the API and providers that implement/maintain the API:

• External API:
  • goal: how to encapsulate the implementation details while encouraging changes (extensions for as many different kinds of features as possible)
  • such as: between the backend and frontend (e.g., between programmers in a project's other sub-groups to allow them to develop independently and in parallel)
  • such as: between a platform and completely external developers (e.g., between iOS and app developers or between Unity and game developers)
  • note: all of these methods will be public
  • vision:
    • What services can you provide to encourage other programmers to build their own new functionality?
    • How do you plan to encapsulate them from implementation changes?
    • What objects will be used for communication, making clear:
      • how needed information will be delivered to where it is needed
      • what will be abstractions
      • what things will be immutable
      • what errors may be thrown
      • how to make the process as active as possible (not just giving out raw data)
• Internal API:
  • goal: how to provide paths for extension through addition for expected new features such that, as much as possible, the External API is not impacted
  • such as: between the backend and its future maintenance programmers (e.g., between programmers within the same sub-group)
  • such as: between a platform and developers that port that platform to new technologies (e.g., between Ebay and its mobile and web teams)
  • note: while some of these methods may be public, many will be protected
  • vision:
    • How do you plan to provide paths for extension by adding new subclasses rather than adding new methods to existing classes?
    • What subclasses or implementing classes will be used to extend your part to add new features, making it clear:
      • what kind of additional code someone will be expected to write
      • how to make as many parts of the code as possible closed to modification
      • what errors may be thrown

Examine one person's Cell Society project the perspective of APIs by categorizing each public or protected method in the Model as:

• should not be part of the Simulation API (i.e., it should have been made private)
• should be part of the external API because it serves users/developers (programmers working on the View or Configuration modules)
• should be part of the internal API because it serves providers/maintainers (programmers working within the Simulation modules)

A simplified view of only the public/protected methods for each team is available here.

Now that you have a sense of the kind of service your project actually provides to programmers, think about the kind of service you wish it provided. In other words, spend this time designing the API instead of just having it happen. Write a simplified (i.e., less than "one page" each) description and goals of both the internal and external Model API. Note which classes are abstract/interface and which concrete and, for concrete classes that are part of the external API, justify why they do not need to represent an abstraction.

Then describe how to use your new external and internal APIs to do the following tasks:

• external: as a client of the backend, the frontend selects an existing simulation to display and then starts running that kind of simulation, updating its own grid visualization
• internal: a new developer joins the the backend team and adds a new possible kind of simulation that can then be selectable by the frontend

Your written explanation should include both English and Java descriptions of the task:

• English: how do you want programmers to think of the process of using the API to accomplish this task using metaphors or analogies (e.g., event-response paradigm), or standard programming ideas (e.g., step by step or substitution via polymorphism) beyond simply restating the procedural steps
• Java: list the actual Java methods you expect to use from the API to accomplish this task with a comment about how they would be used (e.g., call, implement, or change)
  Note, include any Exceptions you plan to throw because of errors that might occur within your methods.

Before Moving On: Add the following to the file doc/SIMULATION_API.md, and add, commit the file, and push it to your shared slogo_teamNN repository:

• your categorized methods
• External and Internal API one-page designs
• English and Java descriptions for the External and Internal tasks

Project API Design: SLogo

Discuss high level design ideas and possible APIs for the SLogo project without worrying about the implementation details (a specific data structure, the parsing algorithm, or the exact layout and OpenJFX components needed). Also discuss any issues or concerns anyone has about the project's specifications or goals.

Consider the following questions:

• What behaviors (methods) should the Turtle have and what service should it provide?
• When does parsing need to take place and what does it need to start properly?
• What is the result of parsing (not the details of the algorithm) and who receives it?
• When are errors detected and how are they reported?
• What do different commands need to know, when do they know it, and how do they get it?
• What behaviors does the result of a command need to have to be used by the View? 
• How is the View updated after a command has completed execution?
• What value would Controller(s) have in mediating between the Model and View?

Write a simplified description for the Model's External and Internal APIs (i.e., no more than "one page" each) that incorporates your vision for each as well as the classes and methods. Note which classes you expect to be abstractions (e.g., abstract or interface) and which concrete. For the concrete classes, justify why they do not need to be an abstraction. A class's behavior is its public methods, including any parameters and a return value. These method signatures can be written as they would appear in Java code, but your focus should be on describing their purpose in the class, not their implementation. To summarize a class and its purpose, highlight only the most important methods in this first draft.

Ideally, without any coding or requiring any specific implementation, try to explore trade-offs between several designs and to determine the best one to explore in detail (creating simplified UML style pictures can be helpful here using Markdown).

Class-Responsibility-Collaborator Cards

Now that your team has thought about the problem generally, use CRC cards to refine your design and help you focus on interface instead of implementation issues. A CRC card help show the objects more conceptually and the logical relationship between objects more explicitly, making it is easier to understand, evaluate, and modify a design. Answering the following questions about each class helps see them as smart/anthropomorphic collaborators:

• What active behaviors is this class responsible for (rather than get/set methods)?
  These are the public methods other objects can call on this one without knowing how it implements that behavior.
• What other classes are required to help this class fulfill those responsibilities?
  These other classes will either be passed to this object's constructor or methods, returned from a method, or created by this object itself.
  

Here are some examples of completed CRC cards. In these examples, the actions are given in English, not as a Java method signature (name, parameters, and return type). Your version must be written as a Java signature to provide more details about the flow of the program.

Use Cases

The following scenarios are provided to help test the completeness of your design. By writing the steps needed to complete each case below you will be able to see how effectively your design handles these scenarios and others 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 case. For this exercise each step, try to include both the class used and the method used to accomplish the step.

• The user types 'fd 50' in the command window, sees the turtle move in the display window leaving a trail, and has the command added to the environment's history.
• The user types '50 fd' in the command window and sees an error message that the command was not formatted correctly.
• The user types 'pu fd 50 pd fd 50' in the command window and sees the turtle move twice (once without a trail and once with a trail).
• The user changes the color of the environment's background.

Here are some examples of completed Use Cases. In these examples, the steps are given in English, not as a Java method calls. Your version should be written as a sequence of calls to only those Java methods on your CRC cards to provide more details about the flow of the program.

To make things more interesting, pair up with another team and try to do this part using their CRC cards!

Submitting your Work

At the end of lab, push your team's Markdown files to the doc folder of your provided, shared, slogo_teamNN repository to submit your notes about your teams' discussions.

• COLLECTION_API.md
• SIMULATION_API.md
• SLOGO_APIs.md

Make sure the text of your final commit message is of the form "lab_slogo_design - NetIDs".