Design Recipe Deliverables
Here are the items you need to include for each question:
-
For Each Data Definition:
- A set of struct definitions, if necessary.
- A constructor template that specifies how to build values for this data definition.
- An interpretation, explaining the meaning of each element in the data in terms of the information it represents. The meaning should be the meaning of the data, not of how it used in the program.
- An observer template for examining values of this kind of data.
- Examples if they will be helpful in understanding the interpretation, or for use in tests. If the examples are primarily for use in tests, you may put them near the tests.
- For Each Function:
- Contract: a specification of data definitions for the
arguments and the result. If you write
list-numbered : ListOfNumber Number -> ListOfNumberthen your function must take any list of numbers and any number and produce the output that is described by the purpose statement, unless the contract is qualified by an invariant (WHERE-clause). We will talk about WHERE-clauses in module 7. - Purpose Statement: A short noun phrase describing what the function is supposed to return. Typically phrased in terms of information, not data. Generally takes the form GIVEN/WHERE/RETURNS, where each of these keywords is followed by a short noun phrase. Examples:
- Examples. The examples should illustrate the different behaviors of the function.
- Halting Measure. For every function that calls itself either directly or indirectly, you must include a halting measure, which is a non-negative integer quantity that must decrease at every recursive call. You should be prepared to defend your choice of halting measure at your codewalk. Halting measures are discussed in more detail beginning in Module 05.
- Design Strategy: A short description of how to get from the
purpose statement to the function definition. These will
typically be one of the following phrases:
- Combine simpler functions
- Use template for [data definition] on [variable]
- Divide into cases on [condition]
- Use HOF [mapfcn] on [variable]
- Call a more general function
For the first few problem sets, you will use ONLY strategies 1-3. We will cover the last three in later modules.
When we get closer to the end of the course, we will let you describe your own strategies. Your strategy should be what you would tweet to a friend to describe what you did.
- The function definition. If your strategy is "Use Template", then your code must match the template for the appropriate data definition.
- The tests. Generally, you will define a test suite for each
function by writing
(begin-for-test (check-equal? (length lobs-1) (length (bombs-after-tick lobs-1)) "bombs-after-tick did not return a list the same length as its input") ...)Tests created with begin-for-test will be run at the end of the file.
GIVEN: a temperature in Fahrenheit RETURNS: the corresponding temperature in Celsius GIVEN: a Cat c and a Scene s RETURNS: A scene like s, except that the cat c has been painted on it. GIVEN: a list of numbers lon and a number n WHERE: n = (length lon) RETURNS: a list of numbers like lon, except that each number is multiplied by its distance from the end of the list.You may omit the GIVEN clause by referring to the givens in the RETURNS clause. Sometimes this is easier than writing a GIVENS clause, sometimes it is harder. Examples:
RETURNS: the temperature in Celsius that corresponds to the given Fahrenheit temperature. RETURNS: A scene like the given one, except that the given cat has been painted on it. - Contract: a specification of data definitions for the
arguments and the result. If you write
- For Each Interface:
- Interface names should end in <%> .
- A purpose statement for the interface.
- A data definition of the form
A DataItem is an object of any class that implements DataItem<%>(replace DataItem with the name of your interface.) - For each method in the interface, a contract and purpose statement of the method. Contracts should always be written in terms of data definitions, not interfaces or classes (e.g. DataItem, not DataItem<%> or DataItem%).
- For Each Class:
- Class names should end in % .
- A purpose statement saying what information the class represents.
- A constructor template showing how to build an object of that class.
- Every field (both init-fields and other fields) must have an interpretation stating what kind of data is contained in the field and what that field represents. If there is an invariant relating two or more fields, it must be stated.
- A set of unit tests that exercise every method and function in the class. In our test framework, these will be located outside the class.
- Every method in the class must come from some interface that the class implements. Exception: methods named for-test:... need not be part of any interface, but they may only be used for testing.
- A class may not contain any private methods. Private methods should be written as ordinary functions instead.
- For Each Method:
- A contract that is identical to the contract in the interface.
- A purpose statement that specializes the purpose statement in the interface to the current class.
- Examples, if these are necessary to clarify the purpose statement. These should generally be stated in human-readable language.
- A Design Strategy, if needed to explain the method definition. These can be any tweet-sized description of how your code works.
- Tests. These will be part of the unit tests for the class.
Additional Deliverables and Coding Conventions for Object-Oriented Programs
Last modified: Thu Nov 3 23:31:05 Eastern Daylight Time 2016