--- title: Eboard 07 Documenting programs and procedures number: 07 section: eboards held: 2017-09-08 --- CSC 151.03, 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! * Right now, we're 1/7 of the way through CSC 151. 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.03 Writeup 6 (YOUR NAMES) * [Writeup for class 7](../writeups/writeup07) due Monday at 10:30 p.m. * Document `take` * To: * Subject: CSC 151.03 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) * 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] * 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 ### 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. Do you care about the subject of the email? : Yes : CSC 151.03 Flash Cards Week 2 (YOUR NAME). What do I do when I get the "Firefox is running on another machine" error? : `/home/rebelsky/bin/magic-incantation` Quiz ---- Reminder: Three (or more) reasons I give quizzes * Sam, like many Computers and many College administrators, is malicious. * Lets us practice. Helps us learn at a steady pace. * A more formal self check; you may think you understand, this helps verify that. * Helps us figure out what is important in the material. * Helps Sam figure out where he screwed up. * Reviewing material in the small helps us prepare material for more larger things (like tests) * "The literature" suggests that students have more long-term gains if they have regular low-stakes quizzes. 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?_ * Code has both human readers and computer readers. * Human readers may have to modify or fix or ... your code. * Human readers may have to *use* the code you write. (You use `iota`; I needed to explain what `iota` did to you.) * We focus on the *what* not the *how* The Six P's - a strategy for documenting procedures --------------------------------------------------- _What are they?_ * "I know this. Why can't I remember?" _You didn't use flash cards._ _What do they mean?_ Procedure : name : Choose a name that makes sense. So, `nearest-multiple` not `moose-and-squirrel-encounter-boris-badenov` Parameters : These are the inputs : We need to give types so that the client knows what kinds of inputs to give. : We name these, too. : Names help them make sense `(nearest-multiple stuff other-stuff)` `(nearest-multiple numbers base)` : We use names in the purpose. Purpose : What the procedure does : Note: We use the names from the parameters Produces : Gives the type of result : Gives a name to the result : Just as the names of the parameters are useful when we describe the purpose, the name of the product is useful when we describe the postconditions (or maybe the preconditions) Preconditions : Restrictions on the input (or the state of the system) : Usually more mathematical/formal : May not be necessary if you've done some specifications in the parameters. Postconditions : Provides a formula - More formal explanation of what the procedure does. : Helps us consider subtleties. : Usually in "math" or "code" Most people can make do with the parameters and the purpose. The preconditions and the postconditions are for when we want to be very very careful. Practice -------- Let's do the two-parmameter `max` procedure. E.g., `(max 0 val)` * In pairs, come up with what youwould fill in for the following. * In pairs or triplets of pairs, compare your answers. * _Why is it so quiet?_ ``` ;;; Procedure: ;;; max ;;; Parameters: ;;; val1, a real number ;;; val2, a real number ;;; Purpose: ;;; Computes the maximum of val1 and val2. ;;; Produces: ;;; result, a real number ;;; Preconditions: ;;; [No additional] ;;; Postconditions: ;;; If (val2 - val1) is positive, ;;; result is val2* ;;; If (val1 - val2) is positive, ;;; result is val1* ;;; If (val1 is the same as val2) ;;; result is either val1 or val2* ;;; *If either is inexact, we get the inexact version of val2 or val1, ;;; depending on the situation. ;;; Ponderings: ;;; If either of the parameters are inexact, it gives us an inexact number. ;;; If *both* of the parameters are exact, it gives an exact result. ```