--- title: Eboard 07 Documenting programs and procedures number: 07 section: eboards held: 2017-09-08 --- CSC 151.01, Class 07: Documenting programs and procedures ========================================================== _Overview_ * Preliminaries * Notes and news * Upcoming work * Extra credit * About CS Table * Friday PSA * Questions * Quiz * The need for documentation * The Six P's - a strategy for documenting procedures * A few additional P's * Practice ### News / Etc. * New places/partners! * At the end of today's class, we will be 1/6 of the way through CSC 151. Just sayin'. * Thank you for your hard work in thinking through pair programming issues. I'll have a draft code of conduct ready on Monday. * Sorry that I was not able to create a combined flash card deck. I'm realizing that 70+ decks are hard to manage. * Spatial Reasoning Class ### Upcoming Work * [Writeup for class 6](../writeups/writeup06) due TONIGHT at 10:30 p.m. * Q1: One new thing you learned about pair programming on Wednesday. * Q2: Something you'd like to see in the class code of conduct. * To: * Subject: CSC 151.01 Writeup 6 (YOUR NAMES) * [Writeup for class 7](../writeups/writeup07) due Monday at 10:30 p.m. * Document `take` * To: * Subject: CSC 151.01 Writeup 7 (YOUR NAMES) * [Assignment 3](../assignments/assignment03) due next Tuesday. * Read: [Unit testing with RackUnit](../readings/rackunit) for Monday's class. ### Extra credit (Academic) * CS Table, Tuesday, noon: Machine Ethics. (More info below.) ### Extra credit (Peer) * Les Duke Cross Country Meet, Saturday at 9 a.m., Country Club * Women's Tennis vs. Coe, TODAY at 4:30 p.m., High School (~one mile west on 8th) * Women's Tennis vs. Lake Forest, Saturday at 9 am High School * Women's Tennis vs. Beloit, Saturday at 3 pm High School * Men's Soccer vs. North Central College, Saturday at 1:00 p.m., Springer Field * Women's Soccer vs. University of Wisconsin-Oshkosh, Sunday at 1:00 p.m., Springer Field ### Extra Credit (Misc) * **NEW** Time Management Workshop, Tuesday, 11am, JRC 226. * Host a prospie ### Other Good Things * WinC meeting, Wednesday, 7pm. All welcome. Informal. Food. [zakeliza] or [nashgemm] ### CS Table Info Next week in CS Table we will discuss the ethical decisions that machines have to make as automation plays a larger role in society, and examine some of the ways that machines are already making ethical decisions. We have two readings for the upcoming discussion: Can You Program Ethics Into a Self-Driving Car? N. Goodall. _IEEE Spectrum_, 31 May 2016. Why Machine Ethics? C. Allen, W. Wallach, and I. Smit. _IEEE Intelligent Systems_, July/August 2006. Printed readings are available outside Curtsinger's door (Noyce 3827). Thank you to Jerod Weinman for his help in selecting readings for this week’s topic. *Computer science table (CS Table) is a weekly meeting of Grinnell College community members (students, faculty, staff, etc.) interested in discussing topics related to computing and computer science. CS Table meets Tuesdays from 12:00–1:00pm in JRC 224A. Contact the CS faculty for the weekly reading. Students on meal plans, faculty, and staff are expected to cover the cost of their meals. Visitors to the College and students not on meal plans can charge their meals to the department.* ### Friday PSA * Take care of yourselves. ### Questions It looked like the flash cards were due at 10:30 p.m. in one place and 8:00 p.m. in another and maybe today in a third? : Sorry. I'm working on it. Wednesdays at 8:00 p.m. To our grader. I'm not sure that I successfully exported from Anki. : I'll let you know if you didn't. How many? : 10 would be good. (And that's base ten, not base 2. Because I know one of you will be snarky about it.) What topics do quizzes cover? : Traditionally: previous Friday, Monday, Wednesday : Sam is supposed to tell you topics on Wednesday. Sometimes he forgets. Sometimes the mentors forget to remind him. Quiz ---- Reminder: Three (or more) reasons I give quizzes * Sam is sentient and malicious. * Helps us refresh our memories on what we learned the past week. * Helps us realize the things we may not have mastered as well as we thought we should have. * Forces us to review. * Evidence from the literature suggests that weekly, low-stakes quizzes significantly impacts long-term learning. (For the reasons above.) (Maybe not the first one.) * Self-check for Sam. If you finish early, review the reading on documentation. * No, do not pull up other prior readings in an attempt to help your partner. It's nice, but not acceptable. * The mentors will collect them after the time expires. The need for documentation -------------------------- _Why do we write documentation?_ Alternately, _Why does Sam make us write documentation?_ * Helps us understand (as a human) what our code is doing. * Helps others understand our code. * How to use our procedures. What kinds of inputs they take, what kinds of output they give. * Informal definition (parameters, purpose) * More formal definition to help understand subtleties. * Other people may do more than just use the code you write. * We are going to focus on "client documentation" - What, not how. The Six P's - a strategy for documenting procedures --------------------------------------------------- _What are they?_ * "I know this. Why can't I remember?" _You didnt' use flash cards._ _What do they mean?_ Procedure : The name of the algorithm (or procedure) : We look for good names, like `remove-negatives`, rather than `moose-and-squirrel-vs-boris-and-natasha` Parameters : The kinds of data you put into the procedure (integers, any numbers, lists, procedures, ...) : Names which we can use to refer to those inputs : `remove-negatives` takes as input `lst`, a list of real numbers : We list the parameters in the same input that we expect the client programmer to provide them. Purpose : What it's supposed to do. : Uses the names we described above. Produces : Type of the output: Integer, string, etc. Perhaps exact or inexact. : We could say more about what the value is (e.g., the same list, but without any negative numbers). [Sam traditionally does not include an explanation here.] : name : The name tells us something about what is being produced : We name the produces so that we can talk about them in the preconditions and postconditions. Preconditions : Requirements that your input must meet. For example, you might require that a list contain at least one zero. Postconditions : More specific guarantees about what the product is. Practice -------- Let's do the two-parmameter `max` procedure. ``` ;;; Procedure: ;;; max ;;; Parameters: ;;; value1, a real number ;;; value2, a real number ;;; Purpose: ;;; To compute the maximum of value1 and value2. ;;; Produces: ;;; result, a real number ;;; Preconditions: ;;; [No additional] ;;; Postconditions: ;;; If (value1 > value2) then ;;; result is value1* ;;; If (value2 > value1) then ;;; result is value2* ;;; If (value2 equals value1) then ;;; result is value2 or value1* ;;; *If either value1 or value2 is inexact, the result is inexact. ;;; Hence, it may not exactly equal value1 or value2, even if that ;;; value is the largest. ``` * There is some confusion as to what equals means. E.g. 3.5 vs 7/2 always gives back 3.5 * Note: If either parameter is inexact, max gives back an inexact number.