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 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: csc151-01-grader@grinnell.edu
  • Subject: CSC 151.01 Writeup 6 (YOUR NAMES)
• Writeup for class 7 due Monday at 10:30 p.m.
  • Document take
  • To: csc151-01-grader@grinnell.edu
  • Subject: CSC 151.01 Writeup 7 (YOUR NAMES)
• Assignment 3 due next Tuesday.
• Read: Unit testing with 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. https://spectrum.ieee.org/transportation/self-driving/can-you-program-ethics-into-a-selfdriving-car

Why Machine Ethics? C. Allen, W. Wallach, and I. Smit. IEEE Intelligent Systems, July/August 2006. http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.617.2203&rep=rep1&type=pdf

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.