The Design Recipe - Northeastern University

The Design Recipe - Northeastern University

Contracts, Purpose Statements, Examples and Tests CS 5010 Program Design Paradigms Bootcamp Lesson 2.1 Mitchell Wand, 2012-2017 This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. 1 Module 02 Basic Principles Tools and Techniques

Object-Oriented Programming Designing Data Computing with Lists Interfaces and Classes Designing Functions

Computing with Trees and Graphs Inheritance Designing Systems Computing with Higher-Order Functions Objects with Mutable State

Designing with Invariants Efficiency, Part 2 Thinking about Efficiency 2 Module Objectives Last week, we introduced the Function Design Recipe, and examined the first step, Data Design, in detail.

This week we will talk in more detail about the rest of the steps in the Function Design Recipe. We will also talk about the kinds of bugs you might encounter while running your programs and how to fix them. 3 Lesson Objectives At the end of this lesson, students will be able to: Write a contract and purpose statements for simple functions. Provide examples showing sample arguments and intended results. Write down the examples as human readable

comments within the program. Lesson Outline In this lesson we'll talk about two more steps in the Design Recipe: Step 2: Contract and Purpose Statement Step 3: Examples and Tests We'll also talk about a few other things, like how to choose good names for your functions and variables. The Function Design Recipe The Function Design Recipe 1. Data Design 2. Contract and Purpose Statement

3. Examples and Tests 4. Design Strategy 5. Function Definition 6. Program Review FDR Step 2: Contract and Purpose Statement Contract: specifies the kind of input data and the kind of output data Purpose Statement: A set of short noun phrases describing what the function is supposed to return. These are typically phrased in terms of information, not data. They generally take the form GIVEN/RETURNS, where each of these keywords is followed by a

short noun phrase. When possible, they are phrased in terms of information, not data. 7 Examples of Contract and Purpose Statements ;; f2c: FarenTemp -> CelsiusTemp ;; GIVEN: a temperature in Fahrenheit, ;; RETURNS: the equivalent temperature in ;; Celsius ;; f2mars : FarenTemp -> CelsiusTemp ;; GIVEN: Any temperature in Fahrenheit ;; RETURNS: The mean temperature on the

surface ;; of Mars, in Celsius 8 Examples of Contract and Purpose Statements (2) scene-with-cat : Cat Scene -> Scene GIVEN: a Cat c and a Scene s RETURNS: A Scene like s, except that the Cat c has been painted on it. 9

What makes a good purpose statement? It gives more information than just the contract. For example GIVEN: an Integer and a Boolean RETURNS: an Integer is not a good purpose statement It is specific. Ideally, a reader should be able to figure out what a function returns just by reading the purpose statement perhaps along with examples, other documentation, etc. but WITHOUT reading the code! Good Function Names are Important

A good choice of function name is important. When a function is used in some other piece of code, the reader should be able to tell roughly what a function computes just by looking at its name. If further detail is needed, then the reader can refer to the purpose statement of the function. If the function name is chosen well and the purpose statement is written well, the reader should rarely, if ever, need to refer to the function definition. For more discussion, see What's in a Name? 11 Conventions for Good Function Names Function names should almost always be nouns

Should describe the result of the function e.g. area, not compute-area Predicates should end in ? : e.g., square? (pronounced "huh?", as in "square-huh?") Use first component of the name to distinguish similar functions with different arguments, e.g.: circle-area, ring-area book-price, total-order-price Conventions for Good Names In Racket, "-" and "?" are legal characters that may occur in names. Use the minus sign to separate components of a

name, e.g. total-order-price Use the question mark to name predicates: eg, square? . These are our conventions. Other languages have other conventions; you should follow them. Argument Names We use short names for arguments: b for a Book Or mnemonic names: cost, price Qualified names: mouse-x, bomb-x

Avoid lame names, like list1 . Names should refer to the information, not just the data type, whenever possible. These are our conventions. Your workplace may have different conventions for argument names. Numeric Data Types In Racket, Number includes Complex numbers, so we'll hardly ever use Number. Integer vs. NonNegReal vs. PosReal ? look to the data definition. If your number represents a quantity that is always non-negative (say, a length or an area), then call it a NonNegInt. if we're not dealing with physical quantities, then we'll typically use Integer.

Your function has to handle any value of the type it says in the contract. 15 FDR Step 3: Examples and Tests Examples show sample arguments and results, to make clear what is intended. This may include showing how the function should be called. It should also illustrate the different behaviors of the function. How many examples, and what kind, will depend a lot on the function Examples of Examples (1)

If the function is a linear function of a single input, two examples are sufficient to uniquely determine the function. We saw this for f2c : ;; (f2c 32) = 0 ;; (f2c 212) = 100 17 Examples of Examples (2) If the function takes an argument that is itemization or mixed data, then choose examples from each subclass of the itemization. Example: ;; (next-state "red") = "green"

;; (next-state "yellow") = "red" ;; (next-state "green") = "yellow" If your function uses a cond to divide its inputs into classes, choose examples from each class. Examples of Examples (3) Avoid coincidences in your examples. This example is coincidental: (book-profit-margin (make-book "Little Lisper" "Friedman" 2.00 4.00)) = 2.00 Is the answer 2 because we subtracted 2 from 4, or because it is the third field in the book?

This example is not coincidental: (book-profit-margin (make-book "Little Lisper" "Friedman" 2.00 5.00)) = 3.00 we must have subtracted 2 from 5 to get 3. Make your examples readable ;;; Heres an example: a rocket simulation. ;; INFORMATION ANALYSIS: ;; An Altitude is represented as a Real, measured in meters ;; A Velocity is represented as Real, measured in meters/sec upward ;; We have a single rocket, which is at some altitude and is ;; travelling vertically at some velocity. ;;

;; ;; ;; ;; REPRESENTATION: A Rocket is represented as a struct (make-rocket altitude velocity) with the following fields: altitude : Altitude is the rocket's altitude velocity : Velocity is the rocket's velocity ;; IMPLEMENTATION: (define-struct rocket (altitude velocity)) ;; CONSTRUCTOR TEMPLATE: ;; (make-rocket Real Real)

20 Not-so-readable examples ;; EXAMPLE: ;; (rocket-after-dt (make-rocket 100 30) 0) ;; = (make-rocket 100 30) ;; (rocket-after-dt (make-rocket 100 30) 2) ;; = (make-rocket 160 30) What do these examples illustrate? Where did those values come from? These are very simple structures, but for more complicated structures youd have a hard time telling. and so would your grader, or boss!

And if you change the representation of rockets, youll have to change all your examples, too! 21 Better Examples (define rocket-at-100 (make-rocket 100 30)) (define rocket-at-160 (make-rocket 160 30)) ;; (rocket-after-dt rocket-at-100 0) = rocket-at-100 ;; (rocket-after-dt rocket-at-100 2) = rocket-at-160 Here weve introduced mnemonic names for each of the example values. These could serve as examples for the data definitions, too. You can inspect those definitions to check whether they represent the rocket they are supposed to represent.

The example is in terms of information, not data. If you decide later to change the representation, you can still use the examples. 22 Turn your examples into tests (begin-for-test (check-equal? (f2c 32) 0) (check-equal? (f2c 212) 100)) Tests live in your file, so they are checked every time your file is loaded Exact technology for tests may change; see the example files for current technology LOTS more to say about testing, but this is enough for now.

23 Summary In this lesson, you have learned how to: Write a contract and purpose statements for simple functions. Provide examples showing sample arguments and intended results. Write down those examples as human readable comments within the program. Turn your examples into executable tests. 24 Next Steps

Study the file 02-1-1-rocket-examples.rkt in the Examples folder. If you have questions about this lesson, post them on the discussion board. Go on to the next lesson. 25

Recently Viewed Presentations

  • Documentation

    Documentation

    Focused: DAR, data, action, response. Often times doesn't include pt, lots of nursing diagnosis and doesn't always tell the whole picture. Flow-sheet: Often found in the inpatient setting, for frequent monitoring or assessments. By exception: new method since computer charting,...
  • Chapter 7: IP Addressing CCNA Routing and Switching

    Chapter 7: IP Addressing CCNA Routing and Switching

    Translation - Network Address Translation 64 (NAT64) allows IPv6-enabled devices to communicate with IPv4 devices. ... it is the link-local address of the router that is used as the default gateway for other devices on the link. ... Cisco IOS...
  • . The Australian Imaging Biomarkers and Lifestyle Flagship

    . The Australian Imaging Biomarkers and Lifestyle Flagship

    Current Focus. Converting all amyloid results to centiloid units and will revisit previous analyses with larger sample size. Quest for a blood biomarker continues internally and via supply of samples to many academic and commercial groups
  • Object oriented Databases. - Illinois State University

    Object oriented Databases. - Illinois State University

    Object Oriented Databases Abhishek Khanolkar Agenda: Service and SOA. Object oriented Databases. Different Architectures MOCHA,SODA. Compare. Conclusion. Questions? Services? In everyday life Cooking, hairdressing and cleaning. Something that adds value to the inputs and gives an output. A service is...
  • Portmarnock Community School Information Evening for Parents /

    Portmarnock Community School Information Evening for Parents /

    Not giving an advantage rather eliminating disadvantage 12 colleges Points reduction and quota Access to a variety of supports Application made as part of CAO Disclose you have a disability Directed to S.I.F. ( Supplementary Information Form) Indicate you wish...
  • Australias Government A Federal Parliamentary Democracy  2014 Brain

    Australias Government A Federal Parliamentary Democracy 2014 Brain

    Have the students complete the Anticipation Guide BEFORE the presentation to gauge what they already know about Australia's government. *There are also economic-related questions in this guide, but the notes in this presentation are government-related only. I have an "Australia's...
  • Grasping and Contact - Duke University

    Grasping and Contact - Duke University

    Low-level loop. State machine controller. Planner. State estimator. Perception module. GUI. Unique features of robots. Some high throughput channels, medium frequency. ... Survey. Don't forget to do official online survey too. Random topics for discussion.
  • Cloud Computing - WordPress.com

    Cloud Computing - WordPress.com

    Standish Group, Chaos Report 2007. Energy Savings. Cloud computing leads to a 38% reduction in worldwide data center energy consumption by 2020. Total data center energy consumption. from $23.3 billion in 2010. to $16.0 billion in 2020.