Prevent Variable Capture in Clojure Macros

Macro hygiene means the names introduced by a macro should not accidentally collide with names in the caller’s code. Java developers usually rely on lexical scope and compiler checks. Clojure macro authors must also think about names created in generated code.

The rule is simple: if a name is only for the macro’s internal implementation, make it generated and unique.

How Capture Happens

This macro builds its expansion manually and introduces ordinary local names:

1(defmacro bad-benchmark [expr]
2  (list 'let ['start '(System/nanoTime)
3              'value expr]
4        (list 'println
5              "elapsed"
6              (list '- '(System/nanoTime) 'start))
7        'value))

The expansion introduces start before the caller expression runs. If the caller expression also uses start, the macro’s local can capture that reference:

1(let [start 10]
2  (bad-benchmark (+ start 5)))

The call site looks as if start means 10, but the generated code binds a new start first. That is the kind of bug that makes macros feel unpredictable.

Use Generated Locals

Use generated symbols for macro-owned locals:

1(defmacro benchmark [expr]
2  `(let [start# (System/nanoTime)
3         value# ~expr]
4     (println "elapsed"
5              (- (System/nanoTime) start#))
6     value#))

Symbols ending in # inside a syntax-quoted form become unique generated symbols. The caller’s start remains the caller’s local; the macro’s start# is private to the expansion.

Hygiene Decision Table

Intentional Bindings Are Different

Some macros intentionally introduce a name chosen by the caller:

1(with-open [reader (clojure.java.io/reader path)]
2  (.readLine reader))

That is not accidental capture. The caller explicitly supplies reader as a binding name. The danger is introducing hidden names the caller did not choose.

Macro Hygiene Review

Knowledge Check