CSC151 2007S, Class 17: Documentation, Preconditions and Postconditions

Admin:
* Are there questions on the exam?
  * Do we have to differentiate between rational and real?
  * I try not to require you to do things that Scheme does not support.
* Reading for tomorrow: Unit Testing.
* EC for Thursday's convo
  Reframing Disability: New Ways of Seeing and Representing Disability
  * EC for watching YouTube movie on "Accessible Grinnell"
    http://www.youtube.com/watch?v=Y_RuFzzS3So

Overview:
* The need for documentation.
* Verifying preconditions.
* Husk and Kernel programming.
* Lab.

/In addition to writing program code, most programmers write documentation/
* Code is for computers and humans to read
* Documentation is for humans only

Who reads procedures?
* Maintainer: The person or people responsible for making sure that the procedure works.
  * These people must know the inner workings, and the design 
* Client: The person or people who use the procedure in their own procedures
  * These people must know what the procedure does, with some precision

When you first write code, you think "I know what this does and how it
does it"
* Six months from now, you'll forget
* You'll be your own client and maintainer

To support client and maintainer, you need to write comments/documentation
* We'll focus on supporting clients

Write "Six P's" to support clients

Four are "trivial"

;;; Procedure:
;;;   THE NAME
;;; Parameters:
;;;   NAME and TYPE
;;; Purpose:
;;;   A sentence or two high-level description
;;; Produces:
;;;   NAME and TYPE

;;; Procedure:
;;;   modulo
;;; Parameters:
;;;   num1, an integer
;;;   num2, a non-zero integer
;;; Purpose:
;;;   Computes the modulus of num1 and num2.
;;; Produces:
;;;   result, an integer

Last two P's are for subtleties/formality

;;; Preconditions:
;;;   What must be true (other than types) for the procedure to work
;;; Postconditions:
;;;   If num2 is positive,
;;;     0 <= result < num2
;;;     There exists an integer, a, s.t. a*num2 + result = num1

You should always think about the question of "For what parameters will
my procedure work and for what parameters will it fail to work?"

* If the parameters are wrong, what should you do?
* "Pure" prepost model: Whatever you want
* Friendly model: Report an error
  "modulo: expected an integer as the first parameter"
* The friendly model takes more work
  * More programmer work to check the parameters
  * More work for the computer to check
* Looks a bit less elegant

Solution: Write two versions of each procedure,
* One just does the job w/o checking preconditions: kernel
* The other checks the preconditions and then calls the first: husk

How do you report errors?
(error "what went wrong")