CS212 Handouts

1. How can I improve my Scheme programming style and coding efficiency?

• Write short functions, where each function provides a single, well-defined operation. Small functions are easier to read, write, test, debug, and understand.
• Use descriptive variable and function names. If it isn't clear from the name of a function or variable what its purpose is, document it with a descriptive comment. In fact, even if the purpose is evident from the name, it is still worth documenting your code.
• Don't write Pascal (or C) code in Scheme. Use the appropriate predefined functions - look in the class notes, revised report, and other documentations. Don't put a close parenthesis on a line by itself - this can really aggravate programmers who grew up on Lisp or Scheme. Prefer using some kind of a Scheme/Lisp oriented editor. You don't need to stick comments on close parentheses to mark which expression they close.
• Use proper indentation - you should be able to understand the structure of your definitions without noticing the parentheses. In general, the way one indents a form is controlled by the first symbol of the form. When defining a function, for example, you can put the symbol DEFINE, the function name and its arguments on one line, then the body itself. Following the argument list, one inserts a carriage return and lists the expressions in the body of the definition, with each form starting on its own line indented two spaces relative to the open parenthesis of the parent (in this case the DEFINE). This general style - of putting all the significant elements of a form on a single line, followed by a carriage return and the indented body - holds for many Scheme constructs. There are, of course, variations, such as keeping the first clause on the same line as the COND symbol, and the rules are relaxed in different ways to keep line lengths to a manageable size. If you find yourself having trouble fitting everything in even with line breaking and relaxing the rules, either your function names are too long or your code isn't very modular. You should perceive this as a signal that you need to break up your big definitions into smaller chunks, each with a clearly defined purpose, and possibly replace long function names with concise but apt shorter ones.
• Use whitespace appropriately. Use whitespace to separate semantically distinct code segments, but don't use too much whitespace. For example,
  GOOD:

     (define foo
       (lambda (x y)
         (let ((z (+ x y 10)))
           (* z z))))
  
     (define (foo x y)
       (let ((z (+ x y 10)))
         (* z z)))
  

  BAD:

     (define foo(lambda (x y)
       (let((z(+ x y 10)))(* z z))))
  
     (define foo
       (method ( x y )
         (let ( ( z ( + x y 10 ) ) )
           ( * z z )
           )
         )
       )
  

  Although the Scheme reader don't care which you use, most experienced Scheme programmers find the first example much easier to read than the last two.
• Don't use line lengths greater than 80 characters. This makes it more difficult to read when printed out or read on an 80x24 xterm window. In fact, use a line length of 72 characters because it leaves a strip of white space at the edge of the window. When you print code, always use fixed-width fonts.
• EVAL. Various Scheme implementations (such as MzScheme) include an EVAL function. Do not use it!

2. To improve the readability of your code,

• Use COND instead of nested IF statements. Be sure to check for unreachable cases, and eliminate those cond-clauses.
• Use the conventions that your language uses - in our case: use "-" to separate words in an identifier (make-point, not make_point), "?" as the last character of a predicate (point? not isPoint), "!" as the last character for functions that changes some state (= asignment), and "<" ">" around symbols that are classes (types).
• Use your own conventions and stick to them - examples are using asterisks for global variable names (*initial-angle*) that can be modified for different executions, periods for constants (.title.) and percent symbols for an internal global variable (%instance-counter%).

3. Documentation:

• Comment your code. Use three semicolons in the left margin before the definition for major explanations. Use two semicolons that float with the code to explain the routine that follows. Two semicolons may also be used to explain the following line when the comment is too long for the single semicolon treatment. Use a single semicolon to the right of the code to explain a particular line with a short comment. The number of semicolons used roughly corresponds with the length of the comment.
  Example:

     ;;; This function implements the square search loop.  It keeps improving an
     ;;; initial guess until the value is good enough.
     (define (try guess x)
        ;; If it's good enough guess - return it, otw, try improving.
        (if (good-enough? guess x)
          guess
          (try (improve guess x) x))) ; loop back
  

4. Stylistic preferences:

• Don't use LET to bind only methods use LETREC
• Don't use lists where vectors are more appropriate. Accessing the nth element of a vector is faster than finding the nth element of a list, since the latter requires pointer chasing while the former requires simple addition. Vectors also take up less space than lists.
• Use local variables in preference to global variables whenever possible. Do not use global variables in lieu of parameter passing. Global variables can be used in the following circumstances:
  • When one function needs to affect the operation of another, but the second function isn't called by the first.
  • When a called function needs to affect the current or future operation of the caller, but it doesn't make sense to accomplish this by returning multiple values.
  • To provide hooks into the mechanisms of the program.
  • Parameters which, when their value is changed, represent a major change to the program.
  • For state that persists between invocations of the program. Also, for state which is used by more than one major program.
  • To provide convenient information to the user (version etc).
  • To provide customizable defaults.
  • When a value affects major portions of a program, and passing this value around would be extremely awkward. (The example here is output and input streams for a program. Even when the program passes the stream around as an argument, if you want to redirect all output from the program to a different stream, it is much easier to just rebind the global variable.)
• Beginning students, especially ones accustomed to programming in C, Pascal, or Fortran, tend to use global variables to hold or pass information in their programs. This style is considered ugly by experienced Scheme programmers. Although assignment statements can't always be avoided in production code, good programmers take advantage of Scheme's functional programming style before resorting to SET!. For example, they will nest function calls instead of using a temporary variable and use the stack to pass multiple values. When first learning to program in Scheme, try to avoid SET! and their cousins as much as possible. And if a temporary variable is necessary, bind it to its first value in a LET statement.

� 1999 Cornell University Computer Science