Lab: Documenting Your code

Assigned

Monday, 16 November 2020

Summary

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

One of you will be a designated “notetaker” for this lab. The notetaker should create a Racket file, documentation.rkt, and share their screen. Ultimately, the notetaker will submit this file on behalf of the group as the lab for this class period. Bre prepared to discuss any of these along the way.

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 our normal documentation approach.

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

Exercise 2: More doc comments

What follows are a series of Racket functions and examples of their execution. 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 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.