English for Racket Developers

Racket’s whole identity is “a programmable programming language,” and describing that precisely needs vocabulary most languages don’t require at all — macro hygiene, language extension, and continuations aren’t peripheral concepts here, they’re what most serious Racket discussions are actually about.

Key Vocabulary

Macro (syntax-rules / syntax-parse) — code that transforms other code at compile/expand time before it’s evaluated, letting Racket programs introduce genuinely new syntactic forms rather than being limited to ordinary function calls, distinct from a simple text-substitution macro. “We can’t implement this as a function, since the arguments need to stay unevaluated until we’ve inspected them — that’s exactly what a macro is for, transforming the syntax itself before any evaluation happens.”

Hygiene (hygienic macros) — a guarantee that identifiers introduced by a macro don’t accidentally capture or collide with identifiers from the code that uses the macro, solving a classic Lisp macro bug where a macro-internal variable name silently shadows a caller’s variable. “This wouldn’t have compiled in an unhygienic macro system — the macro introduces its own tmp variable internally, but hygiene guarantees it can never collide with a tmp variable that happens to exist in the calling code.”

#lang (language extension) — Racket’s mechanism for declaring, at the top of a file, which language that file is written in, since Racket is designed to host entirely different language surfaces — including ones a team defines themselves — on the same underlying platform. “That file isn’t plain Racket — the #lang line at the top declares it’s using our internal DSL for describing API routes, which Racket treats as a genuinely distinct language, not just a library.”

Continuation — a first-class representation of “the rest of the computation” at any given point, which Racket exposes directly to programs (via call/cc and related constructs), enabling control-flow patterns like generators, backtracking, and coroutines without special-casing them into the language. “We’re implementing the generator with a captured continuation instead of a hand-rolled state machine — call/cc lets us literally suspend and later resume the rest of the computation from exactly where it paused.”

Contract (Racket contracts) — a runtime-checked specification attached to a function or module boundary describing what values are acceptable, distinct from a static type system, catching violations at the boundary where a bad value was actually passed in rather than deep inside the function. “Wrap this exported function with a contract requiring a positive integer — now if a caller passes a negative number, the error points directly at the call site that violated the contract, not somewhere three functions deep inside our implementation.”

Common Phrases

• “Does this need to be a macro, since we need unevaluated syntax, or would a plain function work?”
• “Is this macro actually hygienic, or could its internal identifiers collide with the caller’s?”
• “What #lang is this file using — plain Racket, or a custom language?”
• “Are we using a continuation here, or hand-rolling the equivalent state machine?”
• “Is this boundary protected by a contract, or are we trusting callers to pass valid values?”

Example Sentences

Explaining why a macro was necessary: “We couldn’t write this as a function because the second argument needs to stay unevaluated until we check a condition — a macro lets us control exactly when and whether that argument gets evaluated, which a function call can’t do.”

Describing a language-extension design: “Our config files use a custom #lang so non-engineers on the team can write structured configuration in a syntax we designed specifically for readability, while it still compiles down to ordinary Racket underneath.”

Explaining a contract violation in review: “The bug wasn’t actually inside this function — it was a negative value passed in from three calls up the stack. Once we added a contract to this boundary, the very next test run pointed directly at the real offending call site.”

Professional Tips

• Reach for a macro only when you genuinely need control over evaluation timing or need to introduce new syntax — for everything else, a plain function is simpler to read, test, and reason about.
• Trust Racket’s hygiene guarantee, but still choose macro-internal identifier names thoughtfully — hygiene prevents accidental capture, not confusing or misleading macro-expansion output when something does go wrong.
• Use #lang deliberately when defining an internal DSL — it’s a serious commitment to language-level tooling (syntax highlighting, error messages, documentation), not just a convenient way to reuse syntax-rules.
• Reach for a continuation when the control-flow pattern you need (generators, backtracking, coroutines) is naturally expressed that way — but recognize it’s a powerful, unusual tool that needs a comment explaining why it was chosen.
• Add contracts at module and function boundaries that cross team ownership — that’s where invalid values actually originate, and a contract turns a confusing internal failure into an immediate, precisely located error.

Practice Exercise

1. Explain the difference between a macro and a function in terms of when arguments get evaluated.
2. Describe what macro hygiene prevents and why it matters in a Lisp-family language.
3. Write a sentence explaining why a contract at a module boundary produces a clearer error than one deep inside a function.