Lab: Documenting Your code

Assigned

Tuesday, 20 April 2021

Summary

In this laboratory, we explore doc comments, preconditions, and postconditions.

Person “A” will be a designated “notetaker” for this lab. The notetaker should create a Racket file, documentation.rkt, and share their screen. At the end of class, the notetaker will submit this file on behalf of the group as the lab for this class period. The notetaker should be sure to share the file with the rest of the group at the end of class. All of these problems should be completed collaboratively, granted there is no switching back and forth in this lab.

Exercise 0: Header

You’ve seen enough labs by this point, you should be able to write your own header for this lab. Be sure to include a link to the webpage, student names, etc. Save your file from the start - and save if often! This is a good habit to prevent loss of code.

Exercise 1: Writing doc comments

Consider a procedure, (greatest-of-list lst), that finds the largest number in a list.

(define greatest-of-list
  (lambda (lst)
    (reduce max lst)))

Write a documentation comment (doc comment) for greatest-of-list following the documentation approach from the reading. Be sure to consider all elements: signature, parameters, preconditions, postconditions, and description. Remember that determining pre-conditions and post-conditions may require experimenting with the function.

;;; (PROCEDURE PARAMS) -> TYPE
;;;   PARAM : TYPE
;;;   PARAM : TYPE
;;; DESCRIPTION

Exercise 2: More doc comments

What follows are a seriers of examples of the execution of string->list, max, and make-string. For each Racket function, study the examples and apply your intuition or knowledge about how the function ought to work to write a doc comment for each function.

When you are done, feel free to compare your work with the API documentation found in the standard library. You will likely notice that the API docs will differ from your doc comments; that is ok—stick with the original comment you collaboratively developed! In a comment alongside each doc comment, note these differences and whether your group believes they are important. If you have any trouble parsing the API documentation, please ask for help!

> (string->list "hello world!")
'(#\h #\e #\l #\l #\o #\space #\w #\o #\r #\l #\d #\!)
> (string->list "\"12345abc67890\"")
'(#\" #\1 #\2 #\3 #\4 #\5 #\a #\b #\c #\6 #\7 #\8 #\9 #\0 #\")
> (string->list "")
'()
> (max 100 10)
100
> (max 2 1024)
1024
> (max 5 2 1 11 3)
11
> (max 10 1.5)
10.5
> (make-string 5 #\!)
"!!!!!"
> (make-string 3 #\0)
"000"
> (make-string 0 #\3)
""

Exercise 3: Checking requirements

a. What must be true about lst in order for greatest-of-list from problem 1 to work correctly? Make a list of all your expectations.

b. Write a procedure, (check-gol-preconditions val) that uses error to report any errors in those preconditions. Here’s a start.

;;; (check-gol-preconditions val) -> void?
;;;   val : any?
;;; Verifies that `val` meets the preconditions of `greatest-of-list`.
;;; If not, stops the program with an error message.
(define check-gol-preconditions
  (lambda (val)
    (cond
      [(not (list? val))
       (error "greatest-of-list expects a list, not" val)]
      [else
       #t])))

c. Here’s a new version of greatest-of-list).

(define greatest-of-list
  (lambda (lst)
    (check-gol-preconditions lst)
    (reduce max lst)))

Check that it issues appropriate error messages when given incorrect inputs.

Exercise 4: Detailed claims

What expectations do you have for the output of greatest-of-list, given that it receives “correct” input? Be as detailed as you can, including thinking about the exactness or inexactness of the input.