• Homework
• Resources

CS3613: Style Guide

A collection of guidelines for writing better code.

How can I improve my Racket 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. The tests should be added for each logical piece of code from an API point of view. In our case, this means that for the interpteres, there is a single block of tests at the end of the file. (This is different from HtDP, where you test each function in itself, since the functions are unrelated.)
• Use descriptive binding names. If it isn’t clear from the name of an identifier 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 C/Java/Python/... code in Racket. Use the appropriate predefined functions — look in the class notes, in the Racket manuals, and other resources. Don’t put a close parenthesis on a line by itself — this can really aggravate programmers who grew up on Lisp or Scheme. If you choose not to use DrRacket to develop your code, use some other Scheme/Lisp oriented editor. You don’t need to stick comments on close parentheses to mark which expression they close.
• DrRacket has several different languages, some have very different execution semantics, and some are not even close to Scheme. Make sure you use the correct language. In our case, this means always using the “determine language from source” option, and using the correct #lang pl ... line.

To improve the readability of your code

• Make sure that your code is properly indented. When in doubt, let DrRacket do it for you, and/or ask in the tutorial. Your code should be easy to read without counting parens or even looking at them.
• 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 Racket reader does not care which of these you use, most experienced Racket programmers find the first example much easier to read than the last two (the first one is not readable without counting parentheses and the second is too sparse to read conveniently).
  As a general rule of thumb: do not use white spaces (especially newlines) after an open paren or before a closing one, and always use white space before a group of open-parens and after a group closing parens.
• It is very rare to use a newline after the first part of a Racket form, even more rare after special form keywords like define, if, let etc. If you think you need one, ask! (Chances are you don’t.)
• Use newlines to separate semantically distinct code segments, not too many so your code look like scattered unconnected lines too 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 terminal window, but more importantly, wider lines cannot be read conveniently (same reason for narrow column widths in newspapers). In fact, it’s better to restrict your code to a line length of 72 characters. 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 does not hold.
• Usually, you should not use cond if there is a single case and then an else case — if is fine for that.
• Avoid using 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 Racket 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 change some state (mutation). Use lower-case names except for constructors (we capitalize them by convention) and defined type names (we use all-caps by convention).
• The most important point is for you to be consistent in your stylistic choices, even if you have reasons for not following the conventions. But make sure you ask if you want to diverge from these guidelines.

Documentation

• Comment your code. A common convention is to use one semicolon for a comment that follows code on the same line, and two semicolons for comments that are on a line of their own, indented as the code that is described. (Some people use three semicolons for toplevel comments, but this is less common.) The way to think about this is that the number of semicolons used roughly corresponds to the length of the comment. In addition, you can have a multi-line comment #|...|# (for example, write more free-form explanations, or comment out pieces of code).
  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) |#