Design Recipe Deliverables

For each question of a problem set, your solution needs to include the following items.

• For each data definition:
  1. A set of struct definitions, if necessary.
  2. A constructor template that specifies how to build values for this data definition.
  3. An interpretation that explains the meaning of each element of the data in terms of the information it represents. That meaning should be the meaning of the data, not some description of how the data are used in the program.
  4. An observer template for examining values of this kind of data.
  5. Examples, if they help readers to understand the interpretation, or for use in tests. If the examples are primarily for use in tests, you may place them near the tests.
• For each function:
  1. Contract: a specification of data types for the arguments and for the result. If you write

     list-numbered : ListOfNumber Number -> ListOfNumber
     

     then your function must take any list of numbers and any number and produce the output specified by the purpose statement, unless the contract is qualified by a precondition or invariant (WHERE clause). We will talk about WHERE clauses in Module 07.
  2. Purpose Statement: short noun phrases describing the arguments and what the function is supposed to return. Typically phrased in terms of information, not data. Purpose statements are usually stated in GIVEN/WHERE/RETURNS style, where each of those keywords is followed by a short noun phrase. Examples:

     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 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 each number is
     multiplied by its distance from the end of the list.
     

     You may omit the GIVEN part by referring to the given arguments in the RETURNS part. Sometimes this is easier than writing the GIVENS part separately, but 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.
     

  3. Examples: the examples should illustrate the different behaviors of the function, and should be designed to help readers to understand the purpose statement more quickly.
  4. Design Strategy: a short description of the idea used to derive the function definition from its purpose statement. Common design strategies include:
     1. combine simpler functions
     2. use template for [data type] on [variable]
     3. divide into cases on [condition]
     4. use HOF [function] on [variable]
     5. call a more general function
     For the first few problem sets, you will probably find yourself using only the first three of these design strategies. Although the strategies listed above are recommended when they apply, you are free to describe your design strategy in your own words, as a tweet-sized description of your thought process that might help course staff to answer the perennial question: What was this programmer thinking?
  5. Function Definition: your definition of the function should make sense to the computer and also to human readers. If your design strategy is "use template", for example, then your function definition should follow the template for the appropriate data type(s).
  6. Tests: you will generally define a separate test suite for each function by writing something like

     (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 using begin-for-test will be executed as though they appeared at the end of the file. In other words, begin-for-test is a magical syntax that allows you to place your unit tests near the function definition(s) they're testing, even if some of the tests refer to functions or values that haven't been defined yet.
• Remember that at the end of every work session, before you commit and push a new version of your partial solution to your GitHub repository, you must commit a form a form that records the time you spent in that work session. Remember that you must commit a copy of your log file

More deliverables will be required when we get to object-oriented programming.