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 any other component 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
• Leads to readable code
• Hard to misuse
• Provides for extension

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

Use Gitlab's markdown format to record the team's discussion in a file called API_EXERCISE.md. Here is a web-based WYSIWYG editor for markdown if you prefer.

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 other people on the team write their code
• the method should be part of the Internal API because it helps future coders extend this component

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 API_CELLSOCIETY.md.

SLogo Architecture 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. When does parsing need to take place and what does it need to start properly?
2. What is the result of parsing and who receives it?
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.

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:

• External: between each of the two sub-groups — how and what they will communicate (making it clear what will remain hidden, just part of the implementation).
  Focus especially on how you plan to separate the graphical interface from the interpreter and how you plan to let them communicate when necessary (including parsing errors).
• Internal: between each sub-group and future maintainers — how to extend your part to add new features (making it clear what kind of code they will be expected to write and what parts of your code you expect to be closed to modification).
  Focus on providing paths for extension through interfaces, inheritance, and design patterns for new functionality you might reasonably expect to be added to the program.

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.

Start by writing a simplified (i.e., no more than one page) description for each of the four APIs in the project. If you have time, pair up with a different team and get feedback on 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 file, API_EXERCISE.md, to your team's Gitlab repository by the end of class. Make sure the document includes everyone's name that worked on it.