CSC151.02 2016S, Class 10: Documentation
========================================

_MathLAN is dead!  It will return some day (hopefully today)_

Overview

* Preliminaries
    * Admin
    * Upcoming Work
    * Extra Credit
    * Questions

Preliminaries
-------------

### Admin

* DrRacket is *not* your enemy.  *I* am your enemy.  When DrRacket
  crashes, it's probably the add-ons that I wrote.
    * Sarah says "Sam *and* DrRacket are your enemies."
* Thanks for putting up with "comedy" yesterday"
* Outcomes of MathLAN death
    * Sam is even more disorganized than normal
    * HW3 is now optional.  If you choose to turn it in, you have
      until Thursday evening.  (Having done it will certainly make
      the upcoming exam easier.)  (It shouldn't hurt you to turn
      it in.  It might help.)
    * You have until Friday for the lab writeup that is due tomorrow.

### Reminders

* See the white board on the north wall of 3813.

### Upcoming Work

* HW 3, due by Thursday night. (optional)
* NO LAB WRITEUP.
* Exam 1, distributed tomorrow, due a week from today (at 10:30 p.m.)
  (Assuming that we can finish writing it.)  Important policy: Five
  hours, two problms mostly right (out of six): Passing grade guaranteed.
    * Make sure to ask questions early; work until you've been stuck
      for ten minutes, then send me a question and moveon to the next
      problem.
    * Start on it early.

### Extra Credit

* Funding for Internship session today, ARH 131, 7:30
* Protest this year's whitewashed Oscars by attending the multicultural
  screening of film with Anna Mae Wong (_Shanghai Express_), 
  Saturday at 4:30 p.m. in JRC 101.
* Social Dance workshop, Bucksbaum Dance Studio, 7pm.  One hour.
    * Meet new people.  Make friends.
    * Good exercise.
    * Woo!
* Other stuff

Questions

_At the mentor sessions, can we ask general questions related to
 the test?  (E.g., "Can we work through this lab problem that is
 incredibly closely related to the exam?")_

> Yes.

An Exercise
-----------

   (define f 
     (lambda (q) 
       (floor (/ (irgb-red q)
                 (max (irgb-red q)
                      (irgb-green q)
                      (irgb-blue q))))))

Explanation: `f` is a procedure that takes in `q`, which is a sandwich
or something, it takes the red value of `q` and then defines it by
some snappy maximum.

This gives you 1 if the red component is the largest component and 0
if the red component is not the largest component.

When we write procedures, it's useful to write documentation that
explains what our procedures do.

Three audiences:

* People who will be using your code.
* People who have to maintain your code.
* Yourself.

In this class, when you write procedures, you also *document* those
procedures.  (Primarily focusing on those who will use your code,
"clients").

We document with words that begin with the letter P (six of them, to
be precise)

    ;;; Procedure:
    ;;;   red-dominates
    ;;; Parameters:
    ;;;   color, an integer-encoded RGB color
    ;;; Purpose:
    ;;;   Determine whether the red component is the largest
    ;;;   of the three components.
    ;;; Produces:
    ;;;   dominates, an integer
    ;;; Preconditions:
    ;;;   [No additional]
    ;;; Postconditions:
    ;;;   If any other component is greater than the red component,
    ;;;     returns 0
    ;;;   Otherwise
    ;;;     returns 1

Preconditions and postconditions are attempts to formalize expectations
about the parameters.

vs.
    ;;; Parameters:
    ;;;   color, a color
    ;;; Preconditions:
    ;;;   color must be in integer-encoded RGB form

Typical snarky student question: "If both the red and the blue component
are 200 and the green component is 100, is the red component really
*the* largest?"

Additional P's

    ;;; Problems:
    ;;;   Doesn't work when every component is 0.

Could fix the problem with

    ;;; Precondition:
    ;;;   color is not black.

P's, continued

    ;;; Practica:
    ;;;   (red-dominates (irgb 200 100 0)) -> 1
    ;;;   (red-dominates (irgb 0 100 200)) -> 0
    ;;;   (red-dominates (irgb 200 200 100)) -> 1

    ;;; Props:
    ;;;   Based on code written by Sam Rebelsky on 2016-02-10.

    ;;; Process:
    ;;;   Divide the red component by the largest component
    ;;;   and do some tricky math.

    ;;; Philosophy:
    ;;;   Useful in procedures that do different things depending
    ;;;   on which component dominates.

Next Exercise
-------------

Sketch the six P's for this procedure

   ;;; Procedure:
   ;;;   red-blue-plus-32
   ;;; Parameters:
   ;;;   color, a color
   ;;; Purpose:
   ;;;   Makes color more purple.
   ;;; Produces:
   ;;;   purpler, a color
   ;;; Preconditions:
   ;;;   color must be an integer-encoded IRGB color
   ;;; Postconditions:
   ;;;   purpler is an integer-encoded RGB color.
   ;;;   The red component is larger by 32, if possible
   ;;;     If (irgb-red color) <= 223, 
   ;;;       (irgb-red purpler) = (+ 32 (irgb-red color))
   ;;;     If (irgb-red color) > 223, (irgb-red purpler) = 255
   ;;;   The green component is the same
   ;;;     (irgb-green purpler) = (irgb-green color)
   ;;;   The blue component is larger by 32, if possible
   ;;;     If (irgb-blue color) <= 223, 
   ;;;       (irgb-blue purpler) = (+ 32 (irgb-blue color))
   ;;;     If (irgb-blue color) > 223, (irgb-blue purpler) = 255
   (define g (section irgb-add <> (irgb 32 0 32)))

WK's Problem
------------

`red-dominates` fails to work when the color is `(irgb 0 0 0)`, 
because then we are dividing by 0.

   (define red-dominates
     (lambda (color) 
       (floor (/ (+ 1 (irgb-red color))
                 (+ 1 (max (irgb-red color)
                           (irgb-green color)
                           (irgb-blue color)))))))

How do we use `red-dominates`?