CSC151 2007S, Class 13: Documenting Programs and Procedures

Admin:
* Are there questions on the exam?  
  I've added some comments to the online version in the Q&A section.
* How I compute your exam grade, if you spend four hours and write
  "There's more to life than CS"
  (max 80 (+ base-grade time-ec errata-ec other-ec))
* There is no reading for tomorrow!
* I have an interview scheduled during office hours this a.m.
  I will, however, be in from noon until 2pm.
* Remember: Thursday extra, Thurday, 4:30, 3821.

Overview:
* The need for documentation.
* The Six P's - a strategy for documenting procedures.
* Practice.
* Continue Raster/RGB lab.

==Documentation==

* There's a reason that they call code code
  * A programming-language algorithm is not immediately obvious
    to most people
  * For people for whom it should be obvious, there are often some
    subtleties (and typos)
* Traditional practice: Along with code, you provide English-language
  *documentation* that explains what (and sometimes how) the code does
* Documentation can be addressed at different audiences
  * One axis: How your audience will "use" your code
    * As library: Care about what it does, not how it does it
    * As codebase: Care about fixing/maintaining/repurposing;
      how in addition to what
  * Second axis: Experience/knowledge level of audience
* In this class, we focus on *what* docuemntation for programmers at
  the same level as you (novices), but with more math skills
* Goal: Every time we write a procedure, we document what that procedure
  does (or is supposed to do)
* In Scheme, semicolons precede comments (notes to the reader)
* In CSC151, we use six P's to describe procedures

;;; Procedure:
;;;   NAME 
;;; Parameters:
;;;   NAME, TYPE
;;; Purpose:
;;;   SENTENCE OR TWO THAT DESCRIBE WHAT THE PROCEDURE IS
;;;   TO DO
;;; Produces:
;;;   NAME, TYPE of value returned by procedure
;;; Preconditions:
;;;   FORMAL LIMITATIONS ON PARAMETERS
;;; Postconditions:
;;;   FORMAL GUARANTEES OF RESULT

* Preconditions and postconditions are tasks for opposing counsel
  * Counsel for client programmer tries to ensure that the postconditions
    will meet the clients needs.  
  * Counsel for library programmer tries to ensure that it is easy for the
    library programmer to write this code, so limits inputs
  * Negative assumptions
    * Library programmers do the minimum possible to meet the postconditions
    * Client programmers like to break procedures

Examples:
max
;;; Procedure:
;;;   max
;;; Parameters:
;;;   val1 ... valn, one or more numbers
;;; Purpose:
;;;   Computes the largest value.
;;; Produces:
;;;   noidea, a number
;;; Preconditions:
;;;   val1 ... valn must all be real numbers
;;; Postconditions:
;;;   noidea is one of val1 ... valn
;;;   noidea - val1 >= 0
;;;   noidea - val2 >= 0
;;;   ...
;;;   noidea - valn >= 0

==Lab!==