Held: Monday, 2 February 2015

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
• Reading: "How Pair Programming Really Works", available at http://www.computer.org/cms/Computer.org/ComputingNow/homepage/2010/0110/W_SW_PairProgramming.pdf.
• Morning EBoard 8 (Source a.m. 8)
• Afternoon EBoard 8 (Source p.m. 8)

Overview

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

Administrivia

• Continue partners for one more day.
• We will discuss quizzes today. I will only record your quiz 2 grade if you got a 9 or 10.
• Note: You can quickly navigate a large Racket file using the (define ...) menu at the top.
• Notes on HW3:
  • Yes, you need to document the smiley procedure using the 6P format.
  • No, you don't ned to document the other procedures. But it's nice if you do (or at least a short comment).
• A new format for today's class: For each topic, you'll spend two minutes talking to your partner about the issues, and then we'll talk about it together as a wohle class.

Upcoming Work

• Assignment 3.
  • Due Tuesday at 10:30 p.m.
  • Don't forget the prologue and epilogue!
• Exam 1 to be distributed on Wednesday.
• Lab writeup for lab 8 (today), due Wednesday: Document the rectangle procedure from the previous lab. http://bit.ly/151-2015S-lab08
• Readings for Tuesday:
  • Output in Scheme
  • Basic Image Operations

Extra Credit Opportunities

Academic

• Wednesday, February 4, 12:00 noon, JRC 101, Scholars' Convication: "The Fight for Economic Justice from the Streets of Chicago" by Virginia Parks.
• Any other event in this Rosenfield symposium.
• Friday, February 6, 12:00 noon, Science 3821, CS Table, Summer Research Opportunities for CS Students
• TEDx Grinnell, sometime in February.

Peer Support (Morning Section)

• Julia's radio show, "The Hot Box". Wednesday night/Thursday morning 1:00-2:00 a.m. Next week's theme might be Spanish in Songs
• Swimming, Conference Championships, February 13-14, The Osgood

Peer Support (Afternoon Section)

• Swimming, Conference Championships, February 13-14, The Osgood

Recommended Events (no EC unless mentioned above)

• #OneGrinnell, Wednesday, February 4 at 4:15 p.m.

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.

Pair Programming

• What did you take from the reading?

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)
• ...