Class 11: Documenting Programs and Procedures

Held: Wednesday, 8 February 2017

We consider documentation for your programs: Why to write documention, when to write documentation, how to write documentation. We also explore the 6P style of documentation that we use in this course.

Preliminaries

Overview

• The need for documentation
• The Six P’s - a strategy for documenting procedures
• A few additional P’s
• Practice

Related Pages

• Eboard 11 (Source)

• Reading: Documenting Procedures

Updates

News / Etc.

• New partners! You know the drill.
• 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 grade 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.
• Approach three: Work on your program away from DrRacket, and send it to MathLAN when you want to do testing. (You can email yourself, or learn fancier approaches.)
• 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].({{ site.baseurl }}/exams/exam1).

Reminders

• 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.
• 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.
• Visit review sessions! I run review sessions on Thursdays at 9am in this room.
• 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.
• 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.
• Track meet this Saturday. Be moderate in all that you do.

Good things to do

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

Documentation

• As we’ve started to see, programming languages provide a way to communicate not only with the computer, but also with other people.
• But sometimes we want to add some English text which we call documentation.
• Why document? Text is often easier to read than code.
• Who is your audience? You have many audiences.
  • People who must maintain and update your code.
  • People who must use your code.
  • People who incorporate your code into a bigger package (arguably, these are people who do both of the previous things).
• You write comments within code for those who must maintain and update your code. You often also write a big picture statement for such folks.
• Most of the comments you write in this class will be for people who are likely to use your code. We call these your client programmers or simply just clients.
• For such folks, we focus on what your procedures do.

The Six P’s

• I prefer to document procedures for client programmers using a careful system, in which we always describe six aspects of the procedure: The name, the parameters, the purpose, the value the procedure produces, the preconditions, and the postconditions.
• The Purpose is intended to give a short, informal, summary of what the procedure does.
• The other three of the first four parameters are used to name things, so that we can refer to them elsewhere.
• The Preconditions formalize requirements that must be met in order for the procedure to function correctly.
• The Postconditions formalize the results of the procedure. They are often expressed in a combination of mathematics, Scheme, and English.
• Remember: The six-P’s are supposed to give the what not the how.
  • I’ll say that again: Focus on what your procedure does, not how it achieves the result.
• Remember: Your goal is to provide enough information that the client can use the procedure, but not so much that it overly limits your implementation.
• We also have a variety of other P’s to use.
  • Practicum: Examples
  • Process: The how. (Sometimes useful)
  • Philosophy: Bigger picture
  • Problems: When things don’t work
  • Props: Citations
  • …

Practice

• We’ll try writing documentation collaboratively for a variety of procedures.
  • I’ll probably ask you to think for a few minutes before answering (and you can talk to your partner)
• (max val1 val2)
• (max val1 val2 ... valn)
• (irgb-average color1 color2)
• (sqrt val)
• …