Style Rules
In addition to basic structure of the design recipes, there are a number of small details that matter when designing programs.
These rules, or style conventions, are common through the world of software development. Different communities have their own conventions, so what's considered proper for one language is not proper for another. Sometimes, even within a programming language, one group of users will use different conventions than another.
And so it is with our course. We have our own set of style conventions which we ask you to follow.
Notation and Naming Conventions
-
Comments that are a permanent part of the program should have TWO semi-colons followed by a space.
These always go at the beginning of the line.
These include purpose statements, type comments, etc.
;; produce number n times 2
-
Comments that go after code on a line should have ONE semi-colon with no following space.
These are comments that would be deleted in a completed program.
- Comments that are temporary should have ONE semi-colon with no following space.
These are comments that would be deleted in a completed program.
Note that the standard formatting for a commented out stub includes both kinds of one-semicolon comments:
;(define (double n) 0) ;this is the stub
Later in the course stubs are in fact deleted from the program.
-
Use names that make sense with respect to the problem and that talk about the information the value represents.
Good names for a variable representing a count of some sort include count, cnt or possibly c.
-
Never use _ in names, use - instead
render-body rather than render_body
-
Data definition names (type names) should use upper camel case
WorldState rather than world-state, world_state or worldState.
- Function names and parameter names should be hyphenated and all lower case
tock-ball, not tock_ball, tockBall, or tockball.
- Functions that produce Boolean should have names that end in ?
pass? or aisle?
- Constant names should be in ALL-CAPS with -, not _.
HEIGHT, STOP-WHEN, not STOPWHEN, STOP_WHEN, or StopWhen.
Design and Layout Choices
- No line should span more than 80 characters.
The bottom right of Dr. Racket shows how long a line is.
Break lines at those points suggested by examples you see on the websites.
Cond clauses, and the three parts of an if expression, should be on all separate lines.
- Your code should be indented using the conventions seen in our examples
ctrl-I on PC, or command-I on Mac, are shortcuts that will automatically indent. It is explicitly
bad style to handin work for which Ctrl-I or commmand-I changes the indentation.
- Spaces where they belong
Use spaces in a manner consistent with the examples you see in lectures, videos etc.
;; This is good
(define (foo n)
(cond [(odd? n) 1]
[(even? n) 2]))
;; This is not
(define(foo n)
(cond[ (odd? n) 1]
[(even? n)2]))
- No dangling parenthesis
No parentheses left dangling on a line without any other text.
(define (double n)
(* 2 n)
) ; This is a dangling parenthesis
- No single function should span more than ten or so lines.
If it does, reconsider your interpretation of the "one task, one function" guideline.
This rule changes when we learn local to cover the body of the local, not
any actual local definitions.
- In the functions section of a program, the most important functions should be first, and the least important ones last
For world programs the main function should come first, followed by the big-bang handler functions.
NOTE: The recipe will naturally have you design the functions in this order, which is part of why this is the best reading order.
- Don't leave extra examples of making the program do something lying around- use check-expects instead.
A Small Comprehensive Example
Good | Bad |
(@signature String -> String)
;; Produce a greeting with "Hello" before string.
(check-expect (greet "World!") "Hello World!")
(check-expect (greet "goodbye") "Hello goodbye")
(check-expect (greet "loneliness") "Hello loneliness")
;(define (greet o) ; stub
; "a")
(@template-origin String)
(@template
(define (greet o)
(... o)))
(define (greet o)
(string-append "Hello" " " o))
|
; string -> string
; (greet "foo") produces "Hello foo"
(define (greet str)
;; put "Hello " before string
(string-append "Hello " str)
)
(check-expect (greet "World!") "Hello World!")
(check-expect (greet "goodbye") "Hello goodbye")
(check-expect (greet "loneliness") "Hello loneliness")
;(define (accio o) ; stub
; "a")
(greet "World!")
(greet "goodbye")
(greet "loneliness")
|