Programming Style Rules

In addition to the basic structure provided by the design recipes, there are a number of details that matter when designing programs. These rules, or style conventions, are common through the world of software development. Different programming languages, communities, organizations, and individual projects have their own conventions and champions. And so it is with our course; this is the set of style conventions that we ask you to follow.

Design and layout choices

• Organize programs top-down.
• Top-down means we move from the most general and important parts to the most specific or auxiliary parts.
• A program source file should consist, in order, of a general statement of purpose, a data definition, a constant definition section (if there are any), a main function, sections for any handler functions, and then any general utility functions.
• You don’t need to design the functions in this order; you just have to arrange the program this way.
• Design concise functions.
• The guideline is one task, one function. Ideally no function should be longer than five to eight lines.
• Note: This rule is relaxed slightly when we learn the local construct.
• Hint: If a function consumes a complex argument and must perform several different tasks, design several functions that all consume the argument, produce a value in the same data collection, and hand it over to the next function:

;; HHState -> HHState

(define (hungry-henry-action-per-clock-tick hh-world-state)

  (bump-tick-value

    (eat-all-cupcakes-in-reach

       (move-hungry-henry-closer-to-wp hh-world-state))))

;; HHState -> HHState

(define (bump-tick-value hh-world-state)

  ...)

;; HHState -> HHState

(define (eat-all-cupcakes-in-reach hh-world-state)

  ...)

;; HHState -> HHState

(define (move-hungry-henry-closer-to-wp hh-world-state)

  ...)

• Piling the code from these three functions into the first one would yield a confusing mess.
• Don’t leave extra code lying around.
• A common form of this is to have miscellaneous calls to your functions in the definitions window. If they’re worth keeping, change them to calls to check-expect. Otherwise, delete them.
• Keep lines short.
• No line of code or comments should span more than 80 characters. It’s very difficult to read a single line of code with many parts, e.g.,

(cond [(> x 0) (sqrt x)] [(= x 0) 0] [(< x 0) (make-error "Negative input")])

• Instead, use line breaks to split it into coherent parts:

(cond [(> x 0) (sqrt x)]

      [(= x 0) 0]

      [(< x 0) (make-error "Negative input")])

• (If they were longer, you might want to put the consequents—the “then” parts—of each cond case on separate lines from the tests.)
• Indent consistently.
• Indenting makes it easier to read your code by exposing its structure. The general rule is to indent by two spaces for each level of nesting, though there are conventional exceptions.
• It’s fine to let DrRacket indent your code for you by typing Ctrl-i (or Cmd-i on OSX). If the result looks wrong, your code probably doesn’t say what you think it does, and you should check your parentheses.
• Separate elements other than parentheses with one space.
• While inconsistent spaces don’t change the functionality of a program, they can make it much harder to read. Use spaces in a manner consistent with the examples you see in lectures.

😀 Good:

(define (foo n)

  (cond [(odd? n) 1]

        [(even? n) 2]))

😫 Bad:

(define(foo n)

  (cond[ (odd? n)1]

       [ (even? n)2]))

• No dangling parentheses.
• There shouldn’t be parentheses left on a line without any other code.

😀 Good:

(define (f l)

  (cond [(empty? l) 0]

        [else (f (rest l))]))

😫 Bad:

(define (f l)

  (cond [(empty? l) 0]

        [else (f (rest l))]

  )

)

Use concise conditionals.

Similarly, do not use an if or cond expression to evaluate an expression and return true or false. For instance,

(if (= x 42) #true #false)

and

(cond [(= x 42) #true]

      [else #false])

are both redundant ways of writing (= x 42).

Notation and naming conventions

• Comments that are a permanent part of the program have two semicolons followed by a space.
  • These include signatures and purpose statements, e.g.,

;; double : Number -> Number

;; Multiplies a number n by 2

• Note that the How to Design Programs textbook doesn’t follow this convention, but it is the exception; this is standard practice when programming in Lisp, Scheme, and Racket.
• Comments that are temporary have one semicolon.
  • These are used, e.g., commenting out code or jotting down notes that you intend to delete before you’re done designing a program.
• Function signatures should be formatted this way:

;; draw-world : WorldState -> Image

• If you prefer, you can omit the function name, as in the examples in the textbook:

;; WorldState -> Image

• Data definition names (type names) should use upper camel case; e.g., WorldState rather than world-state, world_state or worldState. This keeps them distinct from the lowercase-with-hyphens names used for functions and variables and UPPER-WITH-HYPHENS for constants, discussed in the rules below.
• Use short, clear names.
  • The names you give to functions, constants, and variables should be short, but they also need to make sense with respect to the problem; e.g., good names for a variable representing a count of some sort include count or cnt.
  • Focus on the use of a variable rather than its type; e.g., lst is a reasonable mnemonic for a list that has no other identifying properties, but if the list is intended to contain pairs of (x, y) coordinates, a better name would be coords.
  • Join words in a name with hyphens. Racket programmers join-words-with-hyphens, rather than using mixedCaseVariables or joining_with_underscores when naming functions, constants, and variables; e.g., posn-x or tock-ball.
• Predicates—functions that return true or false—should have names that end with ?, e.g., increasing-values?.
  • Note that built-in predicates like empty? have question marks. Only the most basic mathematical predicates like >or = omit the question mark.)
  • Constant names are uppercase; e.g., MAX-LENGTH.

Example

😀 Good:

;; greet : String -> String

;; Produce a greeting by adding "Hello" before a string.

(define (greet str)

  (string-append "Hello " str))

(check-expect (greet "world!") "Hello world!")

(check-expect (greet "and goodbye") "Hello and goodbye")

(check-expect (greet "darkness, my old friend")

              "Hello darkness, my old friend")

😫 Bad:

; string -> string

; (greet "foo") produces "Hello foo"

(define (greet o)

              ;; put "Hello " before string

              (string-append "Hello " o)

)

(check-expect (greet "World!") "Hello World!")

 (check-expect (greet "goodbye")"Hello goodbye")

(check-expect(greet "darkns")    "Hello darkns")

;(define (accio o)  ; stub

;  "a")

(greet "World!")

  (greet "goodbye")

(greet "sddklfkldfakl")

Acknowledgments

Mostly based on notes by Jonathon Gordon who in turn credits John Hughes, Marc Smith, and Gregor Kiczales.