CSC151 2010S, Class 14: Documenting Programs and Procedures

Overview:
* Questions on Exam 1.
* Lessons from yesterday's class.
* The need for documentation.
* The Six P's - a strategy for documenting 
  procedures.
* Practice.

Admin:
* Reading for tomorrow: Homogeneous Lists.
* Advance warning: I will not be in class tomorrow.  
  Prof. Weinman will be running class.
* EC for Rosenfield Symposium this week.
* EC for CS Table on Friday.

Questions on Exam 1
* How do I negate an expression, as in
  (drawing-vshift drawing -(drawing-width drawing))
  (drawing-vshift drawing (* -1 (drawing-width drawing)))
  (drawing-vshift drawing (- (drawing-width drawing)))
* Can you give me a hint on the last one?  
  * mod
* It's doing funky things with my points
  * We'll look at it after class
* Do we have to parameterize the flag of Pakistan?
  No.  I may give you EC if you do so.  But I may not.
* If I do something extra on a problem, but do it wrong, what happens?
  * If you do something wrong, it indicates a failing, and you lose points
* What should our solution to problem #4 look like
(define no-sign
  (lambda (image OTHER-PARAMETERS-YOU-THINK-WILL-BE-USEFUL)
    ...))
* Could you not record your answers in the Eboard.
  * Fine, I'll stop recording them.

Lessons from Yesterday's Class
* Concrete stuff
  * Complementing colors
  * Decrease red by complement -> increase red -> complement
* Conceptual
  * You can do interesting things by combining basic operations
  * It is worthwhile to think about how to undo things
    * Can we always undo a color transformation?
      * We might reload the original image.
      * If we don't have an original image, we can redo the steps necessary to generate that image.
      * Not every transformation has a natural inverse-transformation
      * How do we undo rgb-redder?
        * rgb-redder seems to add a fixed amount to the red component
        * Suppose we complement the color and make that complement redder.  That's the complement of a less-red version of the original color, so we complement again

Scheme Stuff you might have learned
* Procedures can be parameters to other procedures
* Procedures can create new procedures: (compose rgb-redder rgb-darker) is a procedure THAT HAS NO NAME
* Unnamed procedures can be written with
  (lambda (params) body)
  > ((lambda (a b) (+ (square a) (square b)))
     5 6)
     61
 * Where would this be helpful?
   * When we're using a procedure that expects other procedures as parameters


Documentation!
* A lot of code is not immediately obvious to
  the reader.
 * Some readers need to modify/understand our code
 * Some readers (clients) just need to know what it does
 * We have a particular responsibility to the clients to make it clear WHAT our code does
 * We have that same responsibility to ourselves
   * We should know what our procedure is supposed to do in formal enough terms that we can be sure we've succeeded

The Six P's

Practice
* sqrt
* rgb-redder
* max