--- title: Eboard 07 Documenting programs and procedures number: 07 section: eboards held: 2018-02-04 link: true --- CSC 151.01, Class 07: Documenting programs and procedures ========================================================== _Overview_ * Preliminaries * Notes and news * Upcoming work * Extra credit * Questions * The need for documentation * The Six P's - a strategy for documenting procedures * A few additional P's * Practice Preliminaries ------------- ### News / Etc. * New partners! * Quiz 2 returned. * While you may compare answers, I recommend that you *not* compare grades. * I did not catch up as much as I had hoped or expected this weekend. But I'm getting closer. * Today is a "talk" day; there is no lab. ### Upcoming work * [Assignment 3](../assignments/assignment03) due Tuesday. * Reading due before class Wednesday * [Testing your procedures](../readings/rackunit) * [Lab writeup for class 7](../writeups/writeup07), due before class Wednesday. * Documentation for `drop` * "CSC 151.01 Writeup for Class 7 (Your Name)" * Mail to * [Flash cards for week 3](../flashcards03.md) due Wednesday at 5pm. * Exam 1 (take-home) to be distributed in class on Wednesday. * Eeek! * Due the following Tuesday. ### Extra credit (Academic/Artistic) * Role of Music in the Civil Rights Movement. 8pm TODAY in JRC 101. * CS Table, Tuesday, Noon, Day PDR: Ownership in a digital world. * Skim chapter 1 of _The End of Ownership_. * * CS Extra, 4:15 p.m. Thursday, Science 3821: The design of CSC 151 * Drinks and snacks at 4:00 p.m. in the CS Commons * Rosenfield Symposium on Environmental Degradation and Conflict * Particularly Scholars' Convocation Thursday at 11am. * Saturday at 11am: MET broadcast of _L'Elisir D'Amore_. * Visit the two exhibits at the Faulconer Gallery. ### Extra credit (Peer) * _Hope, Hate, and Race: PossePlus Retreat Recap_, February 6 at 11am, JRC 101. * Listen to KDIC Wednesdays at 6pm - Witty banter with co-host and Indian, Arabic, and Farsi music. (Up to two units of extra credit.) * Friday at 8pm, Contra Club Dance in Younker Lounge 1st * Peer editing with SS. ### Extra credit (Misc) ### Other good things * Democratic caucus * Vote tomorrow! ### A few notes on quiz 2 * Since you know the computer is very picky about syntax, you should pay attention to the particular way that things are represented. * Example: There are no greater-than-sign prompts in the output. * Example: Lists do not have commas. * Example: Lists begin with a tick and are surrounded by parentheses. * Nonetheless, I did not take off for minor syntactic errors. ### Why Sam gives quizzes * Give you feedback on whether or not you understand what we're doing. * Give me feedback on how the class as a whole is doing. * Give me feedback on things I should be talking about. * Evidence that low-stakes testing improves learning. ### Questions I was irresponsible and did not send you a reflection on an extra credit opportunity within two days of the event as you require. Can I still send it to you? : You can certainly send it to me. Cross your fingers that I'll still give you extra credit. (Historically I do.) How long do we get for the exam? : Almost one week. : We'll talk about it on Wednesday. Do we have a homework at the same time as the exam? : No. That would be *way* too much work, rather than just somewhat too much work. How does the computer differentiate between symbols and lists given that both start with a tick mark? : Lists also have an open parenthesis. : The tick marks differentiate a procedure call from a list. : Don't put the ticks for symbols inside a ticked list. It looks like my partner and I will be spending about five-to-six hours on assignment 3. Is that what you intended? : No. My hope is that assignments will generally take you three hours (and exams will take you five-to-six hours). : If it's taking longer, we should talk about what's getting in the way. What do good flash cards look like? : Whatever works for you. : Quick/short Q and A. : Expression and value. `(drop 3 (list 'a 'b 'c 'd 'e))` : Parameters: What are the parameters to `take`? : Syntax: How do you express a list of three items? : Concepts: What are the six P's? : Form: How does Sam like to see the Parameters represented? Do we need to write 6P-style documentation for HW3? : No! Can we? : Sure. The need for documentation -------------------------- Review: _Why do we write documentation?_ Alternately, _Why does Sam make us write documentation?_ * Clarify what our code does. Makes sure that others looking at our code understand our reasoning. * Understand the steps in an algorithm. * Subtleties. `(/ a b)` (oh, I should mention that `b` can't be zero) * Expected inputs/parameters * Expected outputs/produces * How everything fits together * Audience * Our future self is one of the people who may need to understand our reasoning. * People who have to use or modify your code. * Things that may be useful to include * Examples; examples help illustrate the other issues * We will focus on documentation for "the client programmer", the person who has to use the procedures that we write. * Documentation is a form of contract: If you give me correct input, I should give you correct output. The Six P's - a strategy for documenting procedures --------------------------------------------------- _What are they?_ _What do they mean?_ A few additional P's -------------------- * Procedure * The name of the procedure * And nothing else * Parameters * Input to the procedure * Their name(s) * Their type(s) * Purpose * General idea of what the procedure is supposed to do. a * Easier to talk about/understand if you know what's being fed into the algorithm. * Produces * Name and type of the result * Preconditions * Requirements in order for the procedure to work (in addition to the type) * You will strike a balancing act between parameters and preconditions. * Parameter: x, a positive integer; Preconditions: [no additional * Parameter: x, an integer; Preconditions: x is positive * Parameter: x, a number; Preconditions: x is a positive integer * You may find that some of the preconditions are non-trivial * The product of a and b (inputs) must be positive * Can refer to the parameters (most frequently) * Can refer to the product * Postconditions * Additional details about the product. * Gives a formal definition, often using math-like or code-like expressions. Additional notes * Documentation usually comes immediately before the procedure. * Good habit is to *write* the documentation first, too. * It is also a good habit to document every procedure. * Why do we use three semicolons rather than the #| ... |#? * Tradition. * Scheme ignores anything starting with a semicolon. Practice -------- We'll write documentation for the two-parameter `max` ``` ;;; Procedure: ;;; max ;;; Parameters: ;;; a, a number ;;; b, a number ;;; Purpose: ;;; To find the larger of a and b. ;;; Produces: ;;; larger-value, a number ;;; Preconditions: ;;; a and b must be real numbers ;;; Postconditions: ;;; * If a >= b and both are exact the result is a ;;; * If b >= a and both are exact the result is b ;;; * If a >= b and either is inexact the result is (exact->inexact a) ;;; * If b >= a and either is inexact the result is (exact->inexact b) ;;; Practica: ;;; ``` If we were doing the N parameter max ``` ;;; Parameters: ;;; v1 ... vn, numbers ``` Alternate postconditions ``` ;;; * result >= a ;;; * result >= b ;;; * If a and b are both exact, result is exact. ;;; * If a or b is inexact, result is inexact. ;;; * If a and b are both exact, result is in { a, b } ;;; * If a or b is inexact, result is in ;;; { (exact->inexact a), (exact->inexact b) } ``` Writeup: Document the procedure `drop`. * Note: You can't drop five things from a list of two elements, so you will need to write a precondition to accommodate that.