CSC 151.01, Class 11: Documenting Programs and Procedures

Overview

• Preliminaries
  • Notes and news
  • Upcoming work
  • Extra credit
  • Questions
• The Six P’s - a strategy for documenting procedures
• Practice

News / Etc.

• New partners! You know the drill.
• I think we’ll set a record on preliminaries today.
• We are celebrating the release of Exam 1 with donut-like substances.
  • Welcome to Sam’s diet plan!
• Please restore my faith in self-gov: Someone volunteer to be the note taker for this class.
• I will be distributing grade records via email tonight
  • I try to keep you posted on what info we have.
  • The computed may be lower than you expect. Don’t worry! We don’t have enough information for a real grade computation.
  • If you would prefer that I not send your grades via email, send me a message (via text or in person, if you’d like), and I’ll remove you from my list. You can then get grades from me in other ways.

Upcoming quiz

• Sectioning
• Lambda expressions
• Input and output
• Types
• And all past things
• Not documenting procedures

Doing work on your own laptop or workstation

Particularly with an exam released, some of you will prefer to work places other than MathLAN.

• Approach one: Virtual machine. In this model, you are running a Linux workstation (like those in MathLAN) on your own computer. It will, of course, be slower than your computer. It requires about 8 GB of disk space and 1 or 2 GB of RAM. Details at Reference -> VM.
• Approach two: Connect to MathLAN via ssh. I do this on the Mac regularly. Details at Reference -> Remote.
• You can come visit me during office hours for help with either approach.

Notes from our graders

• Please follow the subject conventions for your email; it makes it much easier for us to figure out what you’ve submitted.
  • CSC 151.01 Writeup for Class 9 (Samuel A. Rebelsky and Titus Klinge).
• Please carbon-copy your partner so that they have a record. They may not realize it now, but they’ll appreciate it later.
• Make sure to format your code correctly. Remember that Ctrl

  -I is your friend.

• If you make a prediction, and it turns out to be wrong, you should make a note as to what you learned.
• Nest functions! It’s much easier to write (image-show (color-swatch "blue")) than it is to record the value returned by color-swatch and then type (image-show that-number).

Exam 1 distributed

• We will go over the policies and [the questions].(/~rebelsky/Courses/CSC151/2017S/exams/exam1).
• Evidence suggests that DrRacket will corrupt at least one of your exams. Each time you finish a problem, send yourself a copy of your current exam file.
• You can ask me questions on the exam!

Reminders

• Visit review sessions! I run review sessions on Thursdays at 9am in this room.
• Visit mentor sessions! We have mentor sessions on Wednesday and Thursday evenings from 8:00-9:00 p.m. in the CS Commons. Wednesdays will be more Q&A, Thursdays will include sample quizzes.
• Ask questions via email! I’m always happy to (try to) answer questions via email. There is no need to apologize when sending me questions. If I take too long to answer, send another email (or even text, if it’s a reasonable hour).
• Visit me in my office! I’m always happy to see students during my office hours. I prefer that you book me at https://rebelsky.youcanbook.me, but you can also just show up during office hours and hope that I’m not busy.
• Use our tutors! We have tutors available Sunday through Thursday evening from 7-10 p.m. in Science 3813/15.
• We have individual tutors!
  We have individual tutors available for those who take advantage of the above and find that it’s not enough.
• Visit our store! We have office supplies in the commons. Price is free will donation.
• Get news! Feel free to ask me to sign you up for the department mailing list.

Upcoming Work

• Reading: Testing your procedures.
• Lab writeup: 6P-style documentation for irgb-luma. Due Friday before class.

Extra credit (Academic/Artistic)

• Scholars Convocation, Thursday, 9 Feb 2017, 11:00 a.m., JRC 101.
• Thursday extras, Thursday, 9 Feb 2017, 4:15 p.m., Science 3821: Something on computer graphics (visitor from UMN). Let me know if you want the email.
• CS Table, Next Tuesday at noon, 14 Feb 2017. Topic forthcoming.

Extra credit (Misc)

• Update on Admission and Financial Aid Building and Campus Landscape Projects. TODAY, JRC 101, 11:45-1:00. Pizza!

Extra credit (Peer)

• Org fair on Thursday. Noon-1.
• South-Asian Chai time on Friday, at 4pm, in JRC 2nd floor. Be moderate in all that you do.
• Milo the Rapper and Crunchy Kids 9 p.m., Friday, Gardner.
  Be moderate in all that you do.
• Friday-Saturday-Sunday, 17th-19th, Swimming and diving conference championships.
• Saturday the 18th, Symphony Concert. 2-4 p.m. Sound painting and more! In Sebring-Lewis.

Good things to do

• Track meet this Saturday.
• Read the Electronic Frontier Foundation’s Surveillance Self Defense Tips at https://ssd.eff.org/. Your mentor says they are great.

Questions

Exam questions

What should our time logs look like?

• There’s an answer in the exam. Look at the end.

Do we get extra credit if we find errors elsewhere in the Web site?

• No. Then everyone would likely get A+++++++++ grades in the class.

Can we ask you questions?

• Yes.

Suppose we solved one of the problems on the last homework, can we use that solution?

• Yes, as long as you cite yourself. (Taken from HW3 by student 123151 and partner.)

If we can’t sign the second academic honesty statement, do we have to tell you why not?

• While I would appreciate it if you told me, you need not tell me.

Should we cite our classmates if we take ideas from labs and such.?

• I’m okay with general citations. “Some ideas on this exam are based on work done with a partner on lab writeups and quizzes.”

What if we are using particular sources for a particular problem.

• Put the solution in the citation section for that problem.

I have questions on the exam. Can I text you?

• Yes, during reasonable hours.

Other questions

What do they want for the note taker?

• Someone who takes notes that supplement what I write on the eboard, because I don’t get everything on the eboard.

Question about pair programming reading

• Monday!

The Six P’s - a strategy for documenting procedures

• “There’s a reason they call it code. It’s cryptic.”
• English helps!
• English also helps give us a quick overview.
• Most common situation:
  • One person develops procedures
  • Another person uses them
• The client cares mostly about what the procedures do, now how they achieve the goal
  • “irgb-redder” returns a new version of a color that appears redder to most color-able visioned people.
• The documentation is a form of contract
  • “If you give me these kinds of values, I’ll give you back this result.”
  • Consider +, computes sum. (+ 2 3) => 5. (+ “HELLO” “goodbye”) senseless.
• Enter the six P’s.
  • Procedure: Give the name of the procedure irgb-gamma-correct
  • Parameters: Names, types
    • color, a color (NO! might admit “blue”), an integer-encoded RGB color
    • gamma, a real number (we don’t want imaginary numbers, we’re okay with negative and positive real numbers)
  • Purpose: English-language description of what it does. May be slightly ambiguous. gamma corrects
  • Produces: Names and gives a type to the result. We may not do the naming in our code; this makes it easier to refer to. corrected, an integer-encoded RGB color
  • Preconditions: Requirements other than those mentioned in parameters. “[No additional]”
  • Postconditions: Attempts to formalize and disambiguate purpose.

Practice

Let’s do the two-parameter max.

;;; Procedure:
;;;   max
;;; Parameters:
;;;   number1, a real number
;;;   number2, a real number
;;; Purpose:
;;;   Determine the larger of number1 and number2.
;;; Produces:
;;;   maximillian, a real number
;;; Preconditions:
;;;   [No additional]
;;; Postconditions:
;;;   maximillian >= number1
;;;   maximillian >= number2
;;;   maximillian is an element of { number1, number2 }
;;;   maximillian is exact if both number1 and number2 are exact
;;;   maximillian is inexact if either number1 or number2 is inexact

Writeup: Document the irgb-luma procedure from a recent lab.