Coding Conventions

In addition to following the design recipe, we would like you to observe basic style guidelines for your programs. Not observing these very basic guidelines leads to unreadable code and to loss of points.

• Use consistent indenting. The Racket indenter does a very good job.
• No line should span more than 80-90 characters. The position of the cursor, including its position on the line, is shown in the bottom right of the Racket definitions window.
• No function should span more than five to eight lines for now. If it does, reconsider your interpretation of the "one task, one function" guideline. Use help functions to clarify the meaning of pieces of code. See Help Functions below.
• Use function names and variable names that make sense with respect to the problem and the purpose statement. See the section on Naming Conventions below.
• Start the file with the a purpose statement for the file, the requires, and a comment describing how to run the program.
• Then put constant definitions and data definitions.
• Then put your functions and tests. Organize your functions into meaningful groups. Put help functions near the functions that they help. If your tests are short, put them near the function they test. Long test suites can be put at the end of the file.
• If you have multiple test suites, label them in the file so the output shows which test suites are being run. Example:

  "ball-tests"
  (run-tests ball-tests)
  

• Separate distinct sections of your program with visually distinctive separators. I tend to use lines consisting of many semicolons, but you may use asterisks, dashes, or whatever pleases you. If you have sections and subsections, you can use 2 lines of separators between major sections and one line of separators between minor sections.

; ball-after-tick : Ball -> Ball
(define (ball-after-tick b)
  (cond
    [(and (<= YUP (where b) YLO)
       (or (<= (ball-x b) XWALL
             (+ (ball-x b)
               (ball-dx b)))
         (>= (ball-x b) XWALL
           (+ (ball-x b)
             (ball-dx b)))))
     (make-ball
       (- (* 2 XWALL)
         (ball-x (straight b 1.)))
       (ball-y (straight b 1.))
       (- (ball-dx (straight b 1.)))
       (ball-dy (straight b 1.)))]
    [else (straight b 1.)])) 
      

; ball-after-tick : Ball -> Ball
(define (ball-after-tick b)
  (cond
   [(would-hit-wall? b) (ball-at-wall-reversed b)]
   [else (ball-after-straight-move b 1.)]))
      

• Global constants are in upper-case: eg. HEIGHT, WIDTH, BALL-SPEED
• Names of data definitions are in CamelCase: e.g. ListOfNumbers, World, FallingCatKeyEvent . This also goes for things like ListOf<...>.
• Everything else is in lower case, including names of structs and procedures. We use a minus sign ("-") to separate words in procedure names, e.g. cat-speed, world-after-tick.
• Variables are in lower case. There are no formal conventions for these, but I often use the name of the data definition to remind me what kind of value we expect the variable to have. Sometimes I'll abbreviate the data definition name: e.g.
  • ball or b for a Ball
  • lob ListOf<Ball>

  Sometimes I'll use plural names or abbreviations for lists, such as

  • balls or bs for a ListOf<Ball>
• I sometimes use mnemonic names that remind me of the information represented by the variable, such as mouse-x or other-ball.