Held: Wednesday, 10 September 2014

Back to Outline 07 - Writing Your Own Procedures, Continued. On to Outline 09 - Side Effects: Images, Output, and More.

Summary

We consider documentation for your programs - Why to write it, when to write it, how to write it. We also visit the "Six-P" style of documentation that we use in the course and elsewhere.

Related Pages

• Reading: Documenting Your Procedures
• EBoard (Source) (HTML)

Overview

• Debrief on procedures lab.
• The need for documentation.
• The Six P's - a strategy for documenting procedures.
• A few additional P's.
• Practice.

Administrivia

• Please return your flash drives so that I can supply them to the other section of the class.
• Friday's quiz: Emphasis on drawings-as-values and procedures. We may also ask you to document a bit.
• New lab partners! Take a card to figure out where you work.
• New HW partners! I'll take attendance to help you figure out your partners.
  • We'll also end five minutes early.
• Review sessions:
  • Tonight at 8:00 p.m. in the commons (Alex or Evan)
  • Tomorrow at 10:00 a.m. (Sam)
  • Tomorrow night at 7:30 p.m. (Ajuna)

Upcoming Work

• Lab writeup (due Friday): Document the rectangle procedure from the lab on procedures. See link on schedule or list of labs for link to submit it.
• HW 3 assigned. Due next Tuesday.
• Readings for Friday
  • Output in Scheme
  • Basic Image Operations

Extra Credit Opportunities

Academic

• Awesome show at the Faulconer gallery.
• Convo TODAY at noon. "Limiting Armed Drone Proliferation" by Micah Zenko, the Douglas Dillon fellow in the Center for Preventive Action at the Council on Foreign Relations and vice chair of the World Economic Forum Global Agenda Council on Terrorism.
• Any other event in the Rosenfield Drones program.
• CS Extra, Thursday, September 11: Ajuna Kyaruzi '17 on being a SysAdmin (4:30 p.m., Science 3821)
• CS Table, Friday, September 12: Robots for Autistic Children (12:10 p.m., JRC 224A) (Led by students; No faculty present)

Peer Support

• Football Games (???)
• Women's Volleyball home matches (Sat 9/13 @ 2pm and 4pm and Sun 9/14 @ 11am and 1pm in Darby.)
• Men's Tennis home matches (???)
• Women's Tennis (???)
• Anna Christie, Oct. 9-12 (SB plays Marthy)

Reflecting on Procedures

• Two starting questions:
  • What were the key ideas you took from the reading/lab?
  • What were the more difficult issues for you to grasp?
• A few notes from my observations.
  • Try to pick procedure names and parameter names that would make sense to your human reader.
  • If we specify a procedure name, please use that name.
  • Control-up-arrow in the interactions pane brings up a previous command. (You can also use escape-p.)
  • Once you've defined your procedure, you'll need to call it.
    To call a procedure, you write an open parenthesis, the name of the procedure, the inputs (actual parameters), and a close parenthesis.

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 poicture
  • 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 neighbors)
• (max val1 val2 ... valn)
• (neighbor drawing)
• (sqrt val)
• ...