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 due Tuesday.
• Reading due before class Wednesday
  • Testing your procedures
• Lab writeup for class 7, due before class Wednesday.
  • Documentation for drop
  • “CSC 151.01 Writeup for Class 7 (Your Name)”
  • Mail to csc151-01-grader@grinnell.edu
• Flash cards for week 3 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.
  • https://mitpress.mit.edu/sites/default/files/Chapter1_TheEndofOwnership_final.pdf
• 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.