Style Guide

Styling code properly is an important skill to have as a programmer. Proper indentation, naming, and organization improves code readability, which helps you and other people understand your code.

The Guide

Capitalize terms appropriately

Constants should be in all caps with dashes between words (e.g. (define MOON-RADIUS 20) or (define SUN-IMG (circle 35 "solid" "yellow"))). Function names, structure names, examples, and inputs should be all lower case with dashes between words (this is called kebab-case). For example (define (my-function-name my-input-name) (+ my-input-name 3)) or (define posn1 (make-posn 3 4)). Types of data should be title case (e.g. ThisIsADataType or ThisIsAnotherOne).

Organize your program top-down

This means that when you write a solution that contains multiple functions, the primary function should come first, followed by helpers. The functions should be in order of where they appear in the primary function. For example, the following code is organized top-down:

;; my-function : Number String -> Number
;; Add double the string-length to twice the number cubed
(define (my-function n s)
  (+ (double (cube-num n)) (double-length s)))
(check-expect (my-function 2 "hi") 20)
(check-expect (my-function 3 "hello") 64)
 
;; double : Number -> Number
;; Computes 2n
(define (double n) (* n 2))
(check-expect (double 4) 8)
 
;; cube-num : Number -> Number
;; Produces the cube of this number
(define (cube-num n) (expt n 3))
(check-expect (cube-num 5) 125)
 
;; double-length : String -> Number
;; Produces twice the length of this string
(define (double-length s)
  (double (string-length s)))
(check-expect (double-length "goodbye") 14)

Please note that many of the above helper functions were written solely to illustrate the top-down organization we expect.

Title your exercises

Above every exercise please note which exercise it is. Note this does not apply to project homeworks.

Separate data definitions

Data definitions (and their corresponding examples/templates) should be placed at the beginning of the relevant exercise. Data definitions do not need to be repeated if used in multiple exercises.

Use names that make sense

Use names that make sense with respect to the problem, for your data definitions, field names, functions, constants, and parameters.

Formatting

Narrow Lines. Lines should not exceed 120 characters. DrRacket allows you to enable warnings about lines that exceed a certain character limit. To enable this feature, you can go to Edit -> Preferences -> Editing -> General Editing and set Maximum character width guide to 120
Proper Indentation. When expressions don’t fit in a single line, you should indent them properly. Indentation rules vary by constructs.
Breaking expressions apart. Generally, when an expression exceeds 120 characters, you should break the arguments of that expression into several lines. For instance, you should convert the former to the latter

;; Before
(string-append (string-append "a" "b" "c") (string-append "a" "b" "c") (string-append "a" "b" "c") (string-append "a" "b" "c"))

;; After
(string-append (string-append "a" "b" "c")
               (string-append "a" "b" "c")
               (string-append "a" "b" "c")
               (string-append "a" "b" "c"))

Indentation for define. define should be indented such that the keyword and the arguments are on the same line, but the body has to be on the next line, with two spaces before the body’s expression.

(define (f x)
  (+ 1 2))

Indentation for cond. cond should be indented such that its cases are on new lines with two spaces after the keyword. The condition results may be broken apart if the line exceeds 120 characters.

(define (add-up l)
  (cond
    [(empty? l) 0]
    [(cons? l) (+ (first l) (add-up (rest l)))]))

Automatic Formatting

We strongly recommend that you use raco fmt, which is an automatic code formatting tool. By using raco fmt you will be sure to pass all the formatting requirements.

Accessing the Terminal

To use raco fmt, you need to use the terminal (also known as the shell):

On macOS, use the Terminal.
On Windows, start the “Windows PowerShell” program from the Start menu.

Installation

To install raco fmt, first start the terminal as described above.

On Windows, enter the following command:

  & "C:\Program Files\Racket\raco.exe" pkg install fmt

On macOS, enter the following command:

"/Applications/Racket 8.6/bin/raco" pkg install fmt

Using raco fmt

To use raco fmt:

Save your work and close DrRacket.
Start the terminal, which opens a window in your home directory. On Windows, it is C:\Users\<YOUR USERNAME> and on macOS it is /home/<YOUR USERNAME>.
Use the cd command to change the current directory to the directory where you have saved your work.

For example, if your work is on the desktop you would enter:
```
cd Desktop
```

Finally, run raco fmt.

On macOS:

"/Applications/Racket 8.6/bin/raco" fmt -i "your homework.rkt"

On Windows:

 & "C:\Program Files\Racket\raco.exe" fmt -i "your homework.rkt"

(optional) Include `raco` in your `$PATH`

If you are on macOS, you need to setup your $PATH correctly such that raco can be easily called from the command line. Here is a guide on how to do that. Racket distributions on Linux should have automatically done that for you.