CSU660 Style Guide

A collection of guidelines for writing better code.

How can I improve my Scheme coding style and efficiency?

You are given solution code for the homeworks — use them to learn how good programs look like. (If it doesn't look good, ask about it.)
Write short functions, where each function provides a single, well-defined operation. Small functions are easier to read, write, test debug, and understand.
Add tests to your code, make sure that they work. (You can comment them out once you're convinced that your code is correct.)
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.
DrScheme has several different language levels, some have very different execution semantics, and some are not even Scheme. Make sure you use the correct language level.

To improve the readability of your code

Make sure that your code is properly indented. When in doubt, let DrScheme do it for you. Your code should be easy to read even without counting parens.

Use white space appropriately. For example,

Good:
(define (foo x y) (if (< x 0) (let ([z (+ x y 10)]) (- (* z z) 5)) (* y y)))

Bad:

(define (foo x y)(if (< x 0) (let ([z (+ x y 10)]) (- (* z z) 5)) (* y y))) (define ( foo x y ) ( if ( < x 0 ) (let ([ z (+ x y 10) ]) ( - ( * z z ) 5 )) (* y y ) ) ) ; end foo

Although the Scheme reader does not care which if these you use, most experienced Scheme programmers find the first example much easier to read than the last two.
As a general rule of thumb: do not have white space (especially newlines) after an open paren or before a closing one, and always have either white space or another paren before a block of open-parens and after a block closing parens.

Almost never use newlines after certain keywords like define, if, let etc.
Use newlines to separate semantically distinct code segments, not too many so your code look like lines scattered to widely, and not too few so it looks like a pile of text.
Don't use line lengths greater than 79 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.
Use cond instead of nested if statements. Be sure to check for unreachable cases, and eliminate those cond-clauses. Remember that cond tries each case, so there is no need to check in a certain branch that one of the previous conditions did not hold.
Usually, you should not use cond if there is a single case and then an else case — use if.
Try not to use redundant ifs with literal #fs and #ts, these are usually equivalent to some usage of and and or. For example, (if c #t x) is the same as (or c x), (if c x #f) is the same as (and c x), and (if c #f #t) is the same as (not c). Remember that in Scheme any value other than #f is considered true.
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), and ! as the last character for functions that changes some state (= assignment).
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%).

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. In addition, you can have a multi-line comment #|...|# (for example, to comment out test cases).
An example that demonstrates all of these conventions:

;;; 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 a good guess return it, otherwise, improve (if (good-enough? guess x) guess (try (improve guess x) x))) ; loop back #| (< 3.99 (try 2 0) 4.01) |#

Stylistic preferences

The most important point is for you to be consistent in your stylistic choices, even if you have reasons for not following the conventions.
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.