CSC151 2009F, Class 14: Documenting Programs and Procedures

Admin:
* We potentially have prospectives in class today.
  * And yes, we play with prospies in this class
* Are there questions on Exam 1?
  * How do you extract a number from an RGB color
    (rgb-red rgb)
    (rgb-green rgb)
    (rgb-blue rgb)
    Or
    (rgb-red (color->rgb rgb-list))
* There was a mixup on Writeup 3.  (Appeared in labs and assignments,
  but not on schedule.)
  + If you can't get it in until later this week, there will be 
    no penalty.
* There's a new Mac Version of GIMP+MediaScript (ends with .15).  
  You will probably need it in order to work on the next few labs.
* Reading for tomorrow: Homogeneous Lists.
* Quiz 3 returned
  + Unfortunately, mostly "all or none" on each part
  + Try the various commands in part 2 to see if it helps you understand
  + Come see me!
* HW3 and Writeup2 returned.  Let me now if you didn't get comments.
  + Writeup: I check whether or not you tried each problem.
    + All checks on writeups = A
  + Homework: I look at the quality of solutions in addition to your
    success
    + All checks on homework = B
  + Consistency is the hobgoblin of small minds
* We will go over efficient checkerboard drawing today.

Overview:
* The need for documentation.
* The Six P's - a strategy for documenting procedures.
* Practice.

Why come to Grinnell and not Carleton or other schools?
* Warmer than Minnesota
  (There was a TV shot last year of someone using a banana as a hammer.)
* It will make all the nice Grinnellians happy
  * "please, come to Grinnell"
* Grinnellians are annoyingly precise in their questions
* Clearly, Carleton generates a LOT of bad feelings
* Cool dudes like Mad John attend Grinnell
* Clearly, Grinnellians are articulate and wise about what makes
  Grinnell a special place.
  * And the faculty are not the least bit sarcastic
* We want to make the world a better place, and sometimes succeed

Drawing Checkerboards:
* Many checkerboards had bugs.  I typically tested your checkeboards by
  scaling them and shifting them.  
* The smallest set of instructions was 41 words.  It used an illegal
  operation.
* The second smallest was 43 words.  It did not always produce correct
  checkerboards. [BM and KM]
* The third smallest (and the smallest correct) solution I received was 44
  words.  Congratulations to DB, LC, GP, ER.
* In writing solutions, there is a natural tension between three issues:
  * Clarity
  * Generality
  * Conciseness
* Clear and general go hand-in-hand, but conciseness tends to make us do
  things that are neither clear nor general.
* You can always get more concise by being less correct, but that's not
  really an option.
* We'll look at two of my solutions.  One a bit more general and a bit
  clearer, one that's a bit shorter.
* We'll also play a bit with those solutions to see if we can get other
  interesting images.

Documentation!

* There's a reason they call it "code"
  * Generally, code is stuff that's hard to read
* The programmer has a responsibility for making the code more
  readable by other humans
  * Good names for variables and procedures
  * Use whitespace well
  * Write "comments" that tell the reader something about the
    code
* In Scheme, comments are preceded by a semicolon
* Multiple audiences for comments!
  * IN this class
    * Yourself
    * Your colleagues
    * Your profs
  * Bigger packages
    * Someone who has to figure out how your code works
    * Someone who has to USE your procedures, even if they don't
      know how they work

  * When programming for a client, you need to make it clear to the
    client what your procedure does, and when it will and won't work

* Sam's commenting strategy: The Six P's
;;; Procedure:
;;;   THE NAME
;;; Parameters:
;;;   NAME, TYPE
;;;   NAME, TYPE
;;; Purposeo:
;;;   English-language summary of what it's supposed to do

* Formality

;;; Produces:
;;;   Names and types the result
;;; Preconditions:
;;;   Restrictions on the input
;;; Postcondiitions:
;;;   Guarantees  about the result