SLogo API Design Exercise

This exercise asks you to start the process of designing an application programming interface, or API, for others on your team. An API is all the public classes and their public methods in your program. An API, then, is essentially a contract. Once such a contract is in place, developers are enticed to use the API because they know they can rely on it. The design of the APIs is arguably 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 on the main desirable characteristics of an API:

• Easy to learn
• Hard to misuse
• Provides for extension
• Leads to readable code

In your SLogo teams, complete the following activities today:

1. Critique a previous API
2. Create an overall plan for SLogo
3. Use CRC cards to refine your plan, focusing more on the interactions between components than their implementation
4. Create a one page description for each of your APIs
5. Write code to solve some example Use Cases

In the CRC and Use Case 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.

API Critique

Examine one API from a previous Cell Society project and categorize each method from following perspectives:

• the method should not be part of the API (i.e., it should not be public)
• the method should be part of the external API because it helps people on the team working in other parts write their code
• the method should be part of the internal API because it helps future coders within its part extend it

A simplified view of just the public methods for each team is available here.

Once you have classified the primary methods in the project, write a simplified (i.e., less than one page) description of the six APIs in the project (internal and external for each sub-part: simulation, configuration, and visualization) in a markdown file called doc/API_CELLSOCIETY.md within your team's SLogo repository.

SLogo API Design

Consider the following questions as you discuss the basic design elements of the SLogo project. Write a high-level description of the different parts of the project and how they can interact without worrying about the implementation details.

1. What is the result of parsing and who receives it?
2. When does parsing need to take place and what does it need to start properly?
3. When are errors detected and how are they reported?
4. What do commands know, when do they know it, and how do they get it?
5. How is the GUI updated after a command has completed execution?

A picture may be helpful to show how your parts are related to and dependent on each other.

Use Gitlab's markdown format to record the team's discussion in a file called doc/API_SLOGO.md within your team's SLogo repository.

Choose your Classes: 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 is an index card (which nicely limits how much each class can do) that answers the following questions about a class to describe its behavior without getting into the details of how it implements that behavior. Index cards are also useful because they are easy to change and move around to see their relationship visually.

• What actions is this class responsible for?
• 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, or returned from a method, or created by this object internally.
  

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.

When designing classes, one of the strengths of object-oriented design is creating objects model corresponding objects from the real world. However the best way to make an effective class is to "anthropomorphizing" it, i.e., to give it human characteristics and responsibilities — this is often what helps to distinguish a good object-oriented design (a group of intelligent objects collaborating together) from a bad one (a group of passive objects coordinated by a manager object).

Create Your APIs

Now organize your classes into APIs for your project. The SLogo project should have four APIs (two each):

• External: between the view (front end) and model (back end) modules
  • How you plan to separate the graphical interface from the interpreter and how you plan to let them communicate when necessary.
  • What objects will be used for communication: making it clear how needed information will get where it is needed, what will be available and what will be encapsulated, what things will be immutable, and what errors may be thrown.
  • Note, all of these methods will need to be public.
• Internal: within each module (i.e., for its future programmers/maintainers)
  • How you plan to provide paths for extension through interfaces, inheritance, and design patterns for new features you might reasonably expect to be added to the program.
  • What subclasses or implementing classes will be used to extend your part to add new features: making it clear what kind of code someone will be expected to write, what parts of your code you expect to be closed to modification, and what errors may be thrown.
  • Note, while some of these methods may be public, many may be protected or package friendly.

Start by writing a simplified description for each of the four APIs in the project (i.e., no more than one page each). 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, focus only its most important methods in this first draft.

If you have time, pair up with a different team and get feedback on your API.

Check your API: Use Cases

The following scenarios are provided to help test the completeness and flexibility 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.

• 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 Java method calls to provide more details about the flow of the program.

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. To make things more interesting, pair up with another team and try to do this part using their APIs.

Submission

Push your markdown files, doc/API_CELLSOCIETY.md and doc/API_SLOGO.md, to your team's Gitlab repository by the end of class. Make sure the commit message and document includes everyone's NetID that worked on it.