Fundamentals of Computer Science 1 (CS151 2003S)

Notes on Writeup 1

Contents:

General Formatting Notes

I tend to edit your work using the same editor I use for the EBoards. Hence, I'd prefer that you restrict your lines to no more than 72 (or perhaps 80) characters. You should hit a carriage return (<Enter>, on our keyboards) to move on to the next line.

As many of you have learned, you can also use whitespace (spaces, carriage returns, etc.) to make your code easier to read. Please try to do so. One key thing is to put spaces between the actual parameters to a procedure.

Note that the use of three semicolons at the start of a line should be reserved for procedure and program documentation. The rest of the time, you can use one.

Sample Output

I love to see tests in your code. I also like to see commented-out results from your tests. For example,

(type 'type)
; symbol

I also like to see an explanation of what you're doing. One strategy is to have the code and its output appear when I execute your file. (The following is overkill style; use it sparingly.)

(display "Testing the effects of type on the symbol type.")
(newline)
(display "Is it a procedure or a symbol or ...?")
(newline)
(display "(type 'type)")
(type 'type)
; symbol

When you include sample output (using the comment style), make sure that it is actual output. The Grinnell College Academic Honesty Policy notes that it is a violation of our code to forge laboratory results.

Numeric Constants

When you're using numeric constants, like Pi, it helps to define them at the start of your code. That way, if you decide to change the precision or representation, you only need to do so at one place in your code. For example

(define pi 3.14)
(define sphere-volume 
  (lambda (radius)
     (* (/ 4 3) pi radius radius radius)))

Some Notes on the Six (or More) P's

I ask you to use the six P's (and, preferably, to write them in advance of writing the procedure) because I find that they help you think more carefully about what a procedure is supposed to do. My advanced students (and yes, I know that not all of you will go on to be advanced students) report that careful use of the six P's not only helps them as programmers and thinkers, but also sets them apart from colleagues as they go off into industry.

For example, when you're dealing with recursive procedures, one of the first questions you should ask yourself is what type does this procedure return?.

Note that three of the first four P's are essentially names

The preconditions are intended to restrict the inputs (and, perhaps, other aspects of the Scheme environment).

The postconditions are intended to very carefully specify the output. Often, if you specify the output carefully enough, you'll see a pattern that you can use for writing the program.

If you're not careful in your postconditions, you can really confuse people. For example, some of you said that the result of sphere-volume is is measured in the same units as the radius. While I appreciate your attempt to indicate that we don't conver from say, metric to English measures, it strikes me that cubic centimeters and centimeters are different units.

swap-first-two

Let's see how I might use the six P's to document swap-first-two. We'll then reflect on some key lessons.

;;; Procedure:
;;;   swap-first-two
;;; Parameters:
;;;   lst, a list
;;; Purpose:
;;;   Build a new list by swapping the first two elements
;;;   of lst.
;;; Produces:
;;;   newlst, a list.
;;; Preconditions:
;;;   lst must contain at least two elements.
;;; Postconditions:
;;;   (list-ref newlst 0) equals (list-ref lst 1)
;;;   (list-ref newlst 1) equals (list-ref lst 0)
;;;   (list-ref newlst i) equals (list-ref lst i) for all reasonable i.
;;;   lst is not modified in any way.

Note that the postconditions help resolve many ambiguities. For example, if we swap the first two elements of lst, do we affect lst?

Here's some code that might test that question (along with the output I expect given that documentation).

> (define alphabet (list 'a 'b 'c 'd 'e))
> alphabet
(a b c d e)
> (swap-first-two alphabet)
(b a c d e)
> alphabet
(a b c d e)

 

History

Tuesday, 18 February 2003 [Samuel A. Rebelsky]

Wednesday, 19 February 2003 [Samuel A. Rebelsky]

 

Disclaimer: I usually create these pages on the fly, which means that I rarely proofread them and they may contain bad grammar and incorrect details. It also means that I tend to update them regularly (see the history for more details). Feel free to contact me with any suggestions for changes.

This document was generated by Siteweaver on Tue May 6 09:29:26 2003.
The source to the document was last modified on Wed Feb 19 13:40:17 2003.
This document may be found at http://www.cs.grinnell.edu/~rebelsky/Courses/CS151/2003S/Labs/writeup-notes.01.html.

You may wish to validate this document's HTML ; Valid CSS! ; Check with Bobby

Samuel A. Rebelsky, rebelsky@grinnell.edu