EBoard 13: Documenting your procedures

This class will be recorded! Its use is limited to members of the class. Please do not share with others.

Approximate overview

• General administrative stuff [~10 min]
• Getting to E [~5 min]
• Notes on the first SoLA [~0 min]
• On Friday’s Quiz [~15 min]
• Q&A [~10 min]
• Quiz [~10 min]
• Lab [~40 min]

Administrative stuff

Notes and news

• I hope you had a great weekend!
• Since it’s come up a lot: Computers are sentient and malicious. They hate you. They hate all of us. They exhibit this by refusing to behave until you ask an authority figure (like me), at which point they work. It’s all designed as a clever way to embarrass you.
  • When computers don’t work for me, I assume they are getting revenge for telling the world about their plot.
• A note on banging your head against the wall.
  • A bit of frustration is okay.
  • After ten minutes of frustration with CS, you should (a) ask someone for help and (b) move on to something else for a little bit.
• Ways to write dates: (NOT 11/10/20)
  • MONTH DAY, YEAR - okay Nov 16, 2020
  • DAY MONTH YEAR - okay 16 Nov 2020
  • YEAR-MONTH-DAY - okay 2020-11-16 (also helps sort files in date order)
  • MONTH/DAY/YEAR - NOT okay
  • DAY/MONTH/YEAR - NOT okay
  • The last two are ambiguous in many cases.
  • Also, please don’t use two-digit years. We are in the year 2020, not the year 20. I know that most of you were born after the Y2K issues, but it’s still something of importance.
• This week is probably not the one to mention it, but I hope that many of you will continue on to 161.
  • Don’t worry about the comments on the LAs and MP2; you’ll get it!
• Please don’t abuse the “Most of you got this wrong, so you all get credit for it” approach. (I don’t think you would, but I’ve been trained to say it.)

More fun with technology

I’ll demo (or at least attempt to demo).

• It appears that some of you are unsure about how to resubmit.
• You can save the images you make with (image-save img filename). (It should save in the same directory as your racket program is stored or you can give a full pathname.)

Tutoring reminders

• Please use our tutors! They like to work.
  • Those who are working with them say that they are awesome.
• Evening tutoring will be available 3-5 p.m. Sundays and 8-10 p.m. Sundays through Thursdays in the tutoring channel on the CS team.
  • Please don’t expect them to be available, say, 6 p.m. on Sundays.
• Individual tutors are also available.
  • Email or DM me to request an individual tutor.
  • You can also contact our Peer Education Coordinator, Sarah Dahlby Albright, directly.

Upcoming activities

Attend (or watch recording) and send a one-paragraph reflection.

• Noon, Monday, CS Table (+1 token)
• Noon, Thursday, Convocation (+1 token)
  • “Do you have One Hour to Give to Save a Life? QPR is the CPR of Mental Health”
• 3:30, Saturday, Nov. 21st: Maker Space (+1 token)

Upcoming work

• Mini-project 3 (due Wednesday at 10:30 p.m. CST)
• Mini-project 2 redo (due Sunday the 22nd at 10:30 p.m. CST)
• Reading for Tuesday
  • See the schedule
• Lab writeup for today due Tuesday.
• Quiz today: Local bindings (likely a tracing example)
• Quiz tomorrow: Documentation

Getting to E on MPs

• Nothing (or almost nothing) that we can think of to correct/improve.
• Please avoid overly complicated/verbose solutions.
• No (or very little) repetition.
• Generalize when you can. (Not strictly necessary, but will be treated as a net positive.)

Getting to E on MP3

Here’s a sample overly verbose solution to “count the number of times ‘Dorothy’ appears in wizard-words” This would stop you from achieving E.

(define dorothy-count
  (let ([dorothy?
	  (lambda (str)
	    (string-=? str "Dorothy"))])
    (tally string? (filter dorothy? wizard-words))))

Why filter?

(tally dorothy? wizard-words)

Why bother defining dorothy?

(tally (section string-=? <> "Dorothy") wizard-words)

The latter is not required for the current mini-project, but it would be nice.

Getting to E on MP2

• I’ve started making a list of the typical comments on MP2.
  • Terrifyingly enough, this is not necessarily a complete list.
  • No, we haven’t finished grading.
  • We’ve tried to provide enough comments on each assignment that you can get to E, but you should also pay attention to this list.
• Read through these and ask questions about them tomorrow.
• Make sure that you use the correct Luhn algorithm (rather than the Sam Luhn algorithm) in the redo. We’ll probably run our own tests.
• For this rewrite, you may take advantage of anything new you’ve learned.
• No token required for the MP2 redo!

Some deal breakers (drop you to R)

• You don’t seem to be using the error procedure in check-equal?.
• You aren’t computing the Luhn value correctly because you’re not adding the digits in the doubled number.
• Your procedure names do not match the requirements. For example, I don’t see a procedure called luhn-check? or luhn-16-check? even though that’s what the instructions called for. (The instructions currently call for luhn-16-check?. But the first set called for luhn-check?. If you redo, use the 16.)
• Your luhn-16-check? procedure rejects correct strings with spaces in them because they don’t have 16 characters. Make sure to delete the spaces before checking the length.
• I don’t see you using decomposition in any meaningful way. The assignment did ask for it.
• It doesn’t look like your ISBN computation deals with the “X” at the end of the string.

Formatting, documentation, and such (keeps you from E)

• Please put your name and such at top. (See the labs for the standard header.)
• Please follow formatting conventions.
• Please put a blank line bettween procedure
• It’s not clear why you’ve included spaces at the beginning of some lines.
  Please make sure to reindent (Ctrl-I) before submitting.
• lst is a horrible name for a string.
  • More generally, pick names that either imply the type or imply the use.
  • Using str for a string makes it easy for the reader to say “that’s a string”.
  • Using str for an integer will confuse the reader.
  • Using isbn for a string intended to ISBN doesn’t tell the reader that it’s a string, but does tell you the intended use.
  • Using samr doesn’t tell you anything about a type or use.
• Please be careful about your spelling.
• Explaining what you are checking in the tests would help. (Not essential, but useful.)

• Please follow the documentation guidelines. See the examples from class (and elsewhere).

    ;;; (NAME PARAMS) -> TYPE
    ;;;   PARAM : TYPE
    ;;;   PARAM : TYPE
    ;;; DESCRIPTION
    (define NAME
      (lambda (PARAMS)
        BODY))
  

Booleans (keeps you from E)

• (if TEST #t #f) violates the Zen of Booleans. Please fix.
• Comparing a Boolean function to #t also violates the Zen of Booleans.
  Please fix.

Code quality (keeps you from E)

• The computation of the ISBN is ugly. Can you find a cleaner way to do it?
• You should not count on particular Unicode values, such as 32 or 48. Please use char->integer.
  (That will also make it easier for the reader.) More generally, don’t use “magic numbers” that the reader won’t necessarily understand.
• Please don’t redo expensive computations. (This issue won’t keep you from E on this mini-project, but it will on the next.)
• You seem to accept “X” in the middle of ISBN’s. That’s not valid.
• Rather than doing separate seq-num->num and char->integer procedures, why not have a simple digit->value procedure that takes a character that represents a digit as an input, and returns the corresponding value?
• What’s the difference between add-numbers and +? If there is none, what’s the point of defining add-numbers.
• Does not embrace “The Zen of Booleans”. (I’ll try to put together a handout on this.)

Things to know (no effect right now)

• We appreciate that you are giving detailed comments in the documentation. However, we prefer a short comment that explains what the procedure does more than a longer comment on how. For example, (valid-isbn? str) could just say “Verifies that str represents a valid ISBN.”
• The custom in Racket is to separate words in a procedure name with dashes. For example, add-first-second rather than addfirstsecond. It reduces the cognitive load on the reader.
• I prefer focused citations. Not “Sam helped me” but “Sam helped me on figuring out how to convert characters to the corresponding number.” Not “I used ‘this web page’” but “I found ‘this helpful procedure’ on ‘this web page’.”
  • As long as you make a reasonable attempt at citations (and it’s appropriate to get that help), I consider it acceptable. You need not cite the course Web site or the Racket reference pages (but you can/should).
  • Some faculty expect not only details but a wide range of citations, including to the textbook or equivalent.

Some positives

• Nice documentation!
• Nice citations. Thanks for taking the time to do those.
• Good research in finding other procedures that will help!

Notes on learning assessments

I sent these via email. I’ve just replicated them here as a reminder.

• Please read the comments, even if you got an S (1), but especially if you got a U (0).
• Grading is strict (probably stricter than you expected). If procedures break, you get a zero. If you miss part of the problem, you get a zero.
• Make sure to check your procedures on all the examples we give, as well as a few others.
• If you missed three or more learning assessments, you should try to meet with me this week to go over them.
  • I’ve added times Monday 3:30-4:30, Tuesday 2:30-4:30, and Wednesday 2:30-4:30, but you’ll need to DM me for those.
  • Otherwise: https://bit.ly/book-samr
• I’m also happy to chat with you if you got most of the LAs correct.
• Remember: Evening tutors are helpful and individual tutors are available!
• I don’t report grade distributions. Your questions for yourself should be “Does this represent my knowledge?” and “How do I do better next time?” (Either “How do I demonstrate my knowledge?” or “How do I ensure that I have sufficient knowledge?”)

Notes from Friday’s quiz

Friday’s quiz revealed a lot of confusion. It was also harder than I’d planned. So anyone who took it got credit for it. (The two people who would have gotten “Correct” earned an extra token.)

Please ask questions as we go! If you raise your hand, I won’t notice, so we’ll count on the mentors.

Let’s take a look.

Consider the following procedure

(define f
  (lambda (a b)
    (string-append b a b)))

Suppose we call (reduce f (list "W" "X" "Y" "Z")). As you learned recently, reduce unpredictably selects orders of reduction. For example, it could reduce from right to left, as in (f "W" (f "X" (f "Y" "Z"))), but that’s not the only one.

List all the possible orders of reduction (using the form above) and the result you will get from each reduction. You do not need to trace the reductions.

Some of you wrote (f "X" (f "W" (f "Z" "Y"))) as one of your solutions. This is wrong!. Remember: The reduce procedure does not rearrange parameters.

However, you don’t know which order you’re pairing.

Let’s consider a simpler version. Suppose - were not left-associative. How many ways can we parenthesize (3 - 7 - 11 - 42), where parentheses represent order of operations?

I’ll be calling on people randomly.

• A: ((3 - 7) - (11 - 42)) -> -4 - -31 -> 27
• B: (3 - ((7 - 11) - 42)) -> 3 - (-4 - 42) -> 3 - -46 -> 49
• C: (3 - (7 - (11 - 42))) -> 3 - (7 - -31) -> 3 - 38 -> -35 [right associative]
• D: (((3 - 7) - 11) - 42) -> ((-4 - 11) - 42) -> -15 - 42 -> -57 [left associative]
• E: ((3 - (7 - 11)) - 42) -> ((3 - -4) - 42) -> 7 - 42 -> -35

Of course, Racket uses prefix mode, so we write the procedure before the parameters, rather than after the parameters. I’m also going to switch to f and the strings.

• C: (f "W" (f "X" (f "Y" "Z")))
• B: (f "W" (f (f "X" "Y") "Z"))
• A: (f (f "W" "X") (f "Y" "Z"))
• E: (f (f "W" (f "X" "Y")) "Z")
• D: (f (f (f "W" "X") "Y") "Z")

What do these give? That’s what DrRacket is for. But we could trace one. The right-associative one gives the longest string.

     (f "W" (f "X" (f "Y" "Z")))
---> (f "W" (f "X" (string-append "Z" "Y" "Z")))
---> (f "W" (f "X" "ZYZ"))
---> (f "W" (string-append "ZYZ" "X" "ZYZ"))
---> (f "W" "ZYZXZYZ")
---> (string-append "ZYZXZYZ" "W" "ZYZXZYZ")
---> "ZYZXZYZWZYZXZYZ"

The left-associative one should be the shortest.

     (f (f (f "W" "X") "Y") "Z")
---> (f (f (string-append "X" "W" "X") "Y") "Z")
---> (f (f "XWX" "Y") "Z")
---> (f (string-append "Y" "XWX" "Y") "Z")
---> (f "YXWXY" "Z")
---> (string-append "Z" "YXWXY" "Z")
---> "ZYXWXYZ"

Q&A

MP3

Are there other procedures for reading from a file?

Yes. file->string and file->lines. (file->words is the most useful for problem 1; file->string may be useful for Dale-Chall.)

Miscellaneous

How do I get a list of all the procedures in the CSC 151 library?

It’s in the source code, which you can find at https://github.com/grinnell-cs/csc151.

Let bindings

What’s the diff between let and let*?

let evaluates all of the expressions before it binds.

let* evaluates and binds one at a time (which means that you can use a bound variable in the next expression).

(let ([x 10]
      [y x]))

The x is undefined (or the one defined outside the `let)

(let ([x 10]
      [y x]))

The x is the one defined on the prior line.

Documentation

What’s the just-right amount of documentation? “Goldilocks”.

That’s something we learn through practice. Enough that the reader can quickly understand what the procedure does, and no more.

Suppose procedure2 does something to procedure1. Do we add something?

Our goal is to talk about what and not how.

Example from MP3: You may write two procedures, tally-word and count-word.

;;; (tally-word word list-of-words) -> integer?
;;;   word : string?
;;;   list-of-words : list-of string?
;;; Counts how many times word appears in list-of-words, ignoring
;;; case.

;;; (count-word word list-of-words) -> list-of-a-string-and-integer?
;;;   word : string?
;;;   list-of-words : list-of string?
;;; Makes a two-element list consisting of word and the number of
;;; times word appears in list-of-words, ignoring case.

This way, the reader only needs to look in one place to understand what count-word does.

If I got read of tally-word, I would not have to change the doc. for count-word.

CS Table

The major fair is also at noon today (11am-1pm).

Welcome to Grinnell. Things will conflict.

There will be other CS tables. Go to the majors fair.

Quiz

• Don’t forget to bring up
  • The reading for Friday.
  • The eboard for Friday.
  • DrRacket.
  • Your lab code from Friday.
  • Whatever else you think may be of use.
• Not Discord (or anything similar). Other people are not valid resources.

Lab

• Don’t forget to introduce yourselves.
• Please follow naming conventions for your conversations.
• Remember: If you know your group name, you can join even if you haven’t been invited. (That’s why I like you to follow naming conventions.)