Racket代写 | CS 135 Style Guide

CS 135 Style Guide

1 Introduction
The code you submit for assignments, as with all code you write, can be made more
readable and useful by paying attention to style. This includes the placement of comments, choice of variable and function names, whitespace and indentation. None of these
things affect the execution of a program, but they affect its readability and extensibility.
As in writing English prose, the goal is communication, and you need to think of the
needs of the reader. This is especially important when the reader is assigning you a
This document is organized linearly to match the topics covered. The guide is cummulative; new guidelines are added to the old and only rarely replace previous guidelines.
You’re responsible for the style guide up to and including the current lecture module’s
1.1 Some warnings
The examples in the presentation slides, handouts and tutorials/labs are often condensed
to fit them into a few lines; you should not imitate their condensed style for assignments,
because you do not have the same space restrictions.
The design recipe at Waterloo has evolved beyond what is presented in the course textbook “How to Design Programs” by Felleisen, Flatt, Fieldler and Krishnamurthi, MIT
Press 2003 [HtDP]. Their presentation of the design recipe should not be used directly.
However, the spirit of HtDP style remains and the examples in the textbook are good,
particularly those illustrating the design recipe, such as Figure 3 in Section 2.5.
DrRacket (.rkt) files can store rich content that can include images, extended formatting, comment boxes, and special symbols. Using this rich content may make your
assignment unmarkable. Unfortunately, some of the content in the Interactions window
may be “rich” (e.g., rational numbers), and so you should avoid copy-and-pasting from
your interactions window into your definitions window. In addition, code that appears
in a .pdf document (e.g., presentation slides and assignments) may contain hidden or
unusual symbols, so you should not copy-and-paste from those sources either.
For your assignments, save in plain text format. In DrRacket you can ensure your .rkt
file is saved using plain text format by using the menu items: File > Save Other >
Save Definitions as Text.
2 M02: The Basics
Comments should be used for documentation purposes and to explain why code does
what it does.
Racket comments begin with a semi-colon (;). By convention, full-line comments begin
with two semi-colons:
• ;; starts a full-line comment
• ; starts a comment at the end of a line
Use in-line comments sparingly. If you are following this style guide, you should not
need many additional comments. Any such comment can either be put on its own line,
or tacked onto the end of a line of code, providing it fits.
2.2 File header
Your file should start with a header to identify yourself, the term, the assignment and
the problem. There is no specifically required format, but it should be clear and assist
the reader. The following is a good example.
;; ***************************************************
;; Rick Sanchez (12345678)
;; CS 135 Fall 2020
;; Assignment 03, Problem 4
;; ***************************************************
2.3 Line length and indentation
Overly long lines are hard to read. That’s why newspaper columns are generally short.
Try to keep your lines less than 70 characters and definitely no longer than 80 characters
DrRacket has a setting to show when you’ve exceeded the common style guide’s recommended line length:
Edit → Preferences → Editing tab → General Editing sub-tab
→ Maximum character width guide.
If your lines are getting too long, they should be broken at sensible places so that the
code is readable. Code is hard to read if it’s either too horizontal (lines are too long) or
too vertical (lines are so short that there are needlessly many).
Indentation (appropriate spacing at the beginning of each line) plays a big part in readability. It is used to indicate level of nesting, to align related subexpressions (e.g.,
arguments of a function), and to make keywords more visible. DrRacket’s built-in editor
will help with these. If you start an expression (my-fn and then hit enter or return,
the next line will automatically be indented a few spaces. However, DrRacket will never
break up a line for you, and you can override its indentation simply by putting in more
spaces or erasing them. DrRacket also provides a menu item for reindenting a selected
block of code (Racket > Reindent) and even a keyboard shortcut reindenting an entire
file (Ctrl+I in Windows; Cmd-I on a Mac).
Here are examples showing both good and bad indentation and line lengths:
(define (distance posn1 posn2)
(sqrt (+ (sqr (- (posn-x posn2) (posn-x posn1)))
(sqr (- (posn-y posn2) (posn-y posn1))))))
(define (distance posn1 posn2)
(sqrt (+ (sqr (- (posn-x posn2)
(posn-x posn1)))
(sqr (- (posn-y posn2)
(posn-y posn1))))))
;; BAD (too horizontal)
(define (distance posn1 posn2)
(sqrt (+ (sqr (- (posn-x posn2) (posn-x posn1))) (sqr (- (posn-y posn2)
(posn-y posn1))))))
;; BAD (too vertical)
(define (distance posn1 posn2)
(posn-x posn2)
(posn-x posn1)))
(posn-y posn2)
(posn-y posn1))))))
If indentation is used properly to indicate level of nesting, then closing parentheses can
just be added on the same line as appropriate. You will see this throughout the textbook
and presentations and in the GOOD example above. Some styles for other programming
languages expect that you place closing brackets on separate lines that are vertically lined
up with the opening brackets. However, in Racket this tends to negatively effect the
readability of the code and is considered “poor style”.