6 Textual Matters
Warning: On rare occasion a unit test may depend on the indentation of a file. This is extremely rare and must be noted at the top so that readers do not accidentally re-indent the file.
6.1 Where to Put Parentheses
Racket isn’t C. Put all closing parentheses on one line, the last line of your code.
|
|
You are allowed to place all closing parenthesis on a line by itself at the end of long sequences, be those definitions or pieces of data.
|
|
6.2 Indentation
For every file in the repository, DrRacket’s "indent all" functions leaves the file alone.
If you prefer to use some other editor (emacs, vi/m, etc), program it so that it follows DrRacket’s indentation style.
Examples:
|
|
Caveat 1: Until language specifications come with fixed indentation rules, we need to use the default settings of DrRacket’s indentation for this rule to make sense. If you add new constructs, say a for loop, please contact Robby for advice on how to add a default setting for the indentation functionality. If you add entire languages, say something on the order of Typed Racket, see DrRacket support for #lang-based Languages for how to implement tabbing.
Caveat 2: This rule does not apply to scribble code.
6.3 Tabs
in DrRacket: you are all set. It doesn’t insert tabs.
in Emacs: add (setq indent-tabs-mode nil) to your emacs initialization file.
in vi: :set expandtab
6.4 Line Width
A line in a Racket file is at most 102 characters wide.
If you prefer a narrower width than 102, and if you stick to this
width “religiously,” add a note to the top of the file—
This number is a compromise. People used to recommend a line width of 80 or 72 column. The number is a historical artifact. It is also a good number for several different reasons: printing code in text mode, displaying code at reasonable font sizes, comparing several different pieces of code on a monitor, and possibly more. So age doesn’t make it incorrect. We regularly read code on monitors that accommodate close to 250 columns, and on occasion, our monitors are even wider. It is time to allow for somewhat more width in exchange for meaningful identifiers.
So, when you create a file, add a line with ;; followed by ctrl-U 99 and -. In Vi, the command is 99a- followed by Esc. When you separate "sections" of code in a file, insert the same line. These lines help both writers and readers to orient themselves in a file. In Scribble use @; as the prefix.
6.5 Line Breaks
Next to indentation, proper line breaks are critical.
For an if expression, put each alternative on a separate line.
|
|
Each definition and each local definition deserves at least one line.
|
|
All of the arguments to a function belong on a single line unless the line becomes too long, in which case you want to put each argument expression on its own line
|
|
|
6.6 Names
Use meaningful names. The Lisp convention is to use full English words separated by dashes. Racket code benefits from the same convention.
|
|
|
Names are bad if they heavily depend on knowledge about the context of the code. It prevents readers from understanding a piece of functionality at an approximate level without also reading large chunks of the surrounding and code.
Finally, in addition to regular alphanumeric characters, Racketeers use a few special characters by convention, and these characters indicate something about the name:
Character | Kind | Example |
? | predicates and boolean-valued functions | boolean? |
! | setters and field mutators | set! |
% | classes | game-state% |
<%> | interfaces | dc<%> |
^ | unit signatures | game-context^ |
@ | units | testing-context@ |
#% | kernel identifiers | #%app |
/ | "with" (a preposition) | call/cc |
6.7 Graphical Syntax
Do not use graphical syntax (comment boxes, XML boxes, etc).
The use of graphical syntax makes it impossible to read files in alternative editors. It also messes up some revision control systems. When we figure out how to save such files in an editor-compatible way, we may relax this constraint.
6.8 Spaces
Don’t pollute your code with spaces at the end of lines.
If you find yourself breaking long blocks of code with blank lines to aid readability, consider refactoring your program to introduce auxiliary functions so that you can shorten these long blocks of code. If nothing else helps, consider using (potentially) empty comment lines.
In addition, every pair of expressions on a line should have at least one space between the two, even if they’re separated by parentheses.
|
|
6.9 End of File
End files with a newline.