Coding Conventions

In addition to following the design recipe, we would like you to observe basic style guidelines for your Scheme (and later Java) programs:
  1. No line should span more than 80 characters. See bottom right of DrScheme. Break lines at those points suggested by the books (HtDP, HtDC).
  2. No function should span more than five to eight lines for now. If it does, reconsider your interpretation of the "one task, one function" guideline.
  3. Use function names that make sense with respect to the problem. You may also wish to apply this to variable names.
  4. Start the file with globally useful data definitions and constant definitions. Then arrange to place the most important function near the top of the file and the less important ones near the bottom. NOTE: You don't have to develop the functions in this order, you just have to arrange the program this way.
  5. Separate distinct sections of your program with dashed lines that are exactly 80 columns wide.
Not observing this very basic guidelines leads to unreadable code and to loss of points. You're too old for both.

Here are two equally correct, but radically different versions of the same function. Inspect the one on the right before you read the one on the left:

recommended as seen in code walks (average) 

(define (??? a-ball)
  (cond
    [(hitwall? b) (reflect (straight a-ball 1.))]
    [else (straight a-ball 1.)]))
  

(define (??? b)
  (cond
    [(and (≤ YUP (where b) YLO)
	    (or (≤ (ball-x b) XWALL
		  (+ (ball-x b)
		     (ball-dx b)))
		(>= (ball-x b) XWALL
		  (+ (ball-x b)
		     (ball-dx b)))))
       (make-ball
	 (- (* 2 XWALL)
	    (ball-x (straight b 1.)))
	 (ball-y (straight b 1.))
	 (- (ball-dx (straight b 1.)))
	 (ball-dy (straight b 1.)))]
    [else (straight b 1.)]))
Which one do you understand immediately? Which programming style makes sense? Which solution will lose points in the next code walk?

Last modified: Sun Dec 21 16:47:24 Eastern Standard Time 2008