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
1.
2.
3. 4. 5. 6.
7. 8.
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 signatures, purpose statements, etc. • E.g.
;;”double:”Number”->”Number”
;;”multiples”number”n”by”2″
Comments that are temporary should have ONE semi-colon.
• These are comments that would be deleted in a real program. • These include stubs and notes to yourself.
• E.g.
(define”(double”n)”0)”;”this”is”the”stub”
Function signatures should be formatted this way:
• render:”WorldState”->”Image
Use names that make sense with respect to the problem.
• E.g. Good names for a variable representing a count of some sort include count, cnt or possibly c. Do not use _ in names, use – instead
• Eg. render-body rather than render_body
Data definition names (type names) should use ‘upper camel case’
[http://en.wikipedia.org/wiki/CamelCase]
• E.g. WorldState rather than world-state, world_state or worldState.
Function names and parameter names should be hyphenated and not capitalized
• Eg.posn-xortock-ball.
Constant names should be hyphenated like function names, but should be in ALL-CAPS.
• Eg.HEIGHT,STOP-WHEN.
CISC 108 Page !1 of !2
DESIGN AND LAYOUT CHOICES
1.
2. 3.
4. 5.
6. 7.
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 statement, 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. No dangling parenthesis
• No parentheses left dangling on a line without any other text. • E.g.
(define”(double”n)”
“”(*”2″n)”
)”;”This”is”a”dangling”parenthesis;”Don’t”do”this!”
No function should span more than five to ten lines.
• If it does, reconsider your interpretation of the “one task, one function” guideline. • This rule is relaxed when we learn local
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: You don’t have to design the functions in this order, you just have to arrange the program this way.
Use cond rather than if when the template of a function is handling multiple cases of a data definition (e.g. consider that there may be more cases in the future!).
Don’t leave extra examples of making the program do something lying around- use check* expect instead.
A SMALL COMPREHENSIVE EXAMPLE
Good
;;”greet:”String”->”String”
;;”Produce”a”greeting”by”
;;”adding””Hello””before”a”string”o.”
(check-expect”(greet””World!”)””Hello”World!”)”
(check-expect”(greet””goodbye”)””Hello”goodbye”)”
(check-expect”(greet””loneliness”)”
“””””””””””””””Hello”loneliness”)”
Bad
;”string->”string”
;”(greet””foo”)”produces””Hello”foo””
(define”(greet”str)”
“””””””;;”put””Hello”””before”string”
“””””””(string-append””Hello”””str)”
)”
;(define”(greet”o)”;”stub”
;””a”)”
(define”(greet”o)”
“”(string-append””Hello””””””o)”
;(define”(accio”o)”;”stub”
;””a”)”
(greet””World!”)”
(greet””goodbye”)”
(greet””lonliness”)”
(check-expect”(greet””World!”)””Hello”World!”)”
(check-expect”(greet””goodbye”)””Hello”goodbye”)”
(check-expect”(greet””lonliness”)””Hello”lonliness”)”
CISC 108
Page !2 of !2