CSC151.02 2015S, Class 08: Documenting Programs and Procedures ============================================================== * Continue partners for one more day. * No handouts! _Overview_ * Preliminaries. * Admin. * Upcoming Work. * Extra Credit. * Questions. * Debrief on procedures lab. * Pair programming. * The need for documentation. * The Six P's - a strategy for documenting procedures. * A few additional P's. * Practice. Preliminaries ------------- ### Admin * We will discuss quizzes today. I will only record your quiz 2 grade if you got a 9 or 10. * Note: You can quickly navigate a large Racket file using the (define ...) menu at the top. * Notes on HW3: * Yes, you need to document the `smiley` procedure using the 6P format. * No, you don't need to document the other procedures. But it's nice if you do (or at least a short comment). * A new format for today's class: For each topic, you'll spend two minutes talking to your partner about the issues, and then we'll talk about it together as a wohle class. ### Upcoming Work * [Assignment 3](../assignments/assignment.03.html). * Due Tuesday at 10:30 p.m. * Don't forget the prologue and epilogue! * Exam 1 to be distributed on Wednesday. * Lab writeup for lab 8 (today), due Wednesday: Document the rectangle procedure from the previous lab. * Readings for Tuesday: * [Output in Scheme](../readings/output-reading.html) * [Basic Image Operations](../readings/image-basics-reading.html) ### Extra Credit Opportunities #### Academic * Wednesday, February 4, 12:00 noon, JRC 101, Scholars' Convication: "The Fight for Economic Justice from the Streets of Chicago" by Virginia Parks. * Any other event in this Rosenfield symposium. * Friday, February 6, 12:00 noon, Science 3821, CS Table, Summer Research Opportunities for CS Students * TEDx Grinnell, sometime in February. #### Peer Support (Afternoon Section) * Swimming, Conference Championships, February 13-14-15, The Osgood. An hour is good. * Indoor track, next Saturday, time to be announced ### Recommended Events (no EC unless mentioned above) * #OneGrinnell, Wednesday, February 4 at 4:15 p.m. ### Questions _Is there a way we can know if our lab write ups are submitted or not? I am confused if my partner in the classroom submitted the writeup or not._ > You should ask your partner in the classroom. Notes on Quizzes ---------------- Quiz 1: You all had a better process for getting people to be with matching cards. Why didn't you use it? Quiz 2, Problem 1. (define d0 (recolor-drawing "blue" drawing-unit-square)) (define d1 (scale-drawing 30 d0)) (define d2 (hshift-drawing 20 d1)) (recolor-drawing "red" d1) (scale-drawing 1.5 d2) (image-show (drawing->image (drawing-group d1 d2) 50 50)) Two minutes: Discuss with partner. Then Sam has a series of questions. _How big is the image/canvas we draw?_ > 50x50 _After the first expression, `(define d0 ...)`, what is the value of `d0`?_ > 1x1 square, blue, left boundary is 0, top boundary is 0 (mostly right) > 1x1 square, blue, center is at (0,0), left boundary is -0.5 and top boundary is -0.5 (correct) _How could we be more sure?_ > Look it up in the reading > Try it (visual will be hard, textual will be useful) > Ask someone else (e.g., a mentor or professor) _After the second expression, `(define d1 ...)`, what is the value of `d0`? > `d0` does not change, so it is still 1x1 square, blue, center at (0,0) _After the second expression, `(define d1 ...)`, what is the value of `d1`? > `d1` is `d0` scaled by 30. 30x30 blue square, left edge at -15, top edge at -15, right edge at 15, bottom edge at 15 _After the third expression, `(define d2 ...)`, what is the value of `d0`? > Doesn't change _After the third expression, `(define d2 ...)`, what is the value of `d1`? > Doesn't change _After the third expression, `(define d2 ...)`, what is the value of `d2`? > A 30x30 square, left edge at 5, top edge at -15, right edge at 35, bottom edge at 15 _What is the value of the fourth expression, `(recolor-drawing "red" d1)`? > A square, centered at (0,0), 30x30, colored red _After the fourth expression, what is the value of `d1`?_ > What it was before, a square, centered at (0,0), 30x30, colored blue _What is the value of the fifth expression, `(scale-drawing 1.5 d2)`?_ > `d2` was a 30x30 square, centered at (20,0), left edge at 5, top edge at -15, right edge at 35, bottom edge at 15 > The value is a 45x45 square, centered at (30,0), left edge at 7.5, top edge at -22.5, right edge at 52.5, bottom edge at 22.5 > General principle: You can multiple any of the edges by the scale factor. _What does the final image look like?_ Debrief on procedures lab ------------------------- Pair programming ---------------- The need for documentation -------------------------- * People won't figure out what the vocabulary means just by looking at code. * We need to communicate meaning. * *You* can create new vocabulary - every procedure you write is a piece of vocabulary. * You need to communicate that meaning to others. * The most important thing to communicate: What is the goal of the procedure. * But we want to be clear to the speaker/user/client * The 151 model: 6 P's * The word/name: "Procedure" * Inputs: "Parameters" * Name, Type * What it does/goal: "Purpose" * Output/result: "Produces" * Name, Type * Requirements for it to function: Preconditions * Formal guarantees: Postconditions Practice -------- ;;; Procedure: ;;; create-neighbor ;;; Parameters: ;;; d, a drawing ;;; Purpose: ;;; Create a copy of the drawing, immediately to the right ;;; Produces: ;;; neighbor, a drawing ;;; Preconditions: ;;; [No additional] ;;; Postconditions: ;;; (drawing-left neighbor) = (drawing-right d) ;;; Neighbor is the same appearance as d - same colors, shapes, etc. ;;; (drawing-height neighbor) = (drawing-height d) ;;; (drawing-width neighbor) = (drawing-width d) ;;; (drawing-top neighbor) = (drawing-top d) `max`, `neighbor`, and more.