5Textual Matters

Simple textual conventions help eyes find pieces of code quickly. Here are
some of those that are easy to check—some automatically and some
manually. If you find yourself editing a file that violates some of the
constraints below, edit it into the proper
shape.

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.

5.1Where to Put Parentheses

Racket isn’t C. Put all closing parentheses on one line, the last line of
your code.

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, we will need to wait for Matthew and Robby to
provide an indentation protocol on the

#lang

line; please be
patient and use the existing indentation tool anyway.

Caveat 2: This rule does not apply to scribble code.

5.3Tabs

Do not use tab characters in your code. Tabs make it hard to use textual
tools like git or diff effectively. To disable tabs,

5.4Line 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—right below the
purpose statement—that nobody should violate your file-local rule.

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
"-". 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.

The convention is particularly helpful when the same piece of data shows
up in different guises, say, symbols and strings.

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:

symbol

kind

example

?

predicates and boolean-valued functions

boolean?

!

setters and field mutators

set!

#:

keywords

#:dest-dir

%

classes

game-state%

<%>

interfaces

dc<%>

^

unit signatures

game-context^

@

units

testing-context@

#%

kernel identifiers

#%app

The use of “#%” to prefix names from the kernel language warns readers
that these identifiers are extremely special and they need to watch out
for subtleties. Identifiers with this prefix are mostly used in modules
that define new languages.

5.7Graphical 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.

5.8Spaces

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.