Macros and Macro Expansion

Macros are one of Clojure’s most powerful features and one of the easiest to misuse. The shortest correct definition is:

A macro receives unevaluated forms, transforms them, and returns a new form.

That means a macro works on code representation, not on already computed values.

How a macro differs from a function

A function sees evaluated arguments.

1(defn log-value [value]
2  (println "value:" value)
3  value)

A macro sees the form itself before normal evaluation.

1(defmacro log-form [expr]
2  `(let [result# ~expr]
3     (println "expr:" '~expr "result:" result#)
4     result#))

That difference is the entire reason macros exist. If a function can solve the problem, a function is usually the better tool.

What macro expansion means

When you call a macro, Clojure expands it into another form. That expanded form is what eventually gets compiled or evaluated.

You can inspect this process with macroexpand-1 and macroexpand.

1(macroexpand-1 '(when test
2                  (println "ok")))

This shows one level of macro rewriting. That is often enough to understand what a macro is really doing.

For Java developers, macro expansion is a bit like seeing the generated source for a language construct, except the transformation is happening through ordinary language forms rather than a separate code-generation toolchain.

Why macros exist at all

Macros are useful when you need to change evaluation shape, introduce new surface syntax, or build domain-specific constructs that functions cannot express cleanly.

Good macro use cases include:

• control-flow constructs
• binding constructs
• DSL-like syntax where forms themselves matter
• code-generation patterns that would be repetitive or impossible with functions

Bad macro use cases usually sound like:

• “I want a shorter function call”
• “I want to avoid writing one helper function”
• “I want this to look clever”

A simple mental model

Think of a macro as a form rewriter.

It is not:

• “a faster function”
• “a magical metaprogramming badge”
• “the default abstraction tool”

It is a tool for code transformation.

Why macroexpand matters

If you cannot explain the expansion, you do not really understand the macro yet.

That is why macroexpand-1 is such an important debugging tool. It helps answer:

• what code is actually being generated?
• where did the bindings come from?
• why is the evaluation order what it is?

When macros confuse you, inspect the expansion before doing anything else.

Java comparison that helps

Java developers often compare macros to reflection, annotations, or code generation. Those comparisons help a little, but none is exact.

The closest practical comparison is:

• Java often uses separate tooling to generate or inspect code structure
• Clojure can do certain source-level transformations directly in the language

That makes macros feel closer to everyday programming than most Java metaprogramming tools.

Common beginner mistakes

Using a macro where a function is enough

This is the most common mistake. If you do not need to transform code shape or control evaluation, use a function.

Ignoring hygiene and generated names

Macro-generated bindings can capture or clash with user names if written carelessly. Auto-gensyms such as result# exist to reduce that risk.

Forgetting that macros manipulate forms, not values

If your reasoning is based on runtime values, you may be solving the wrong problem.

A practical rule

Ask this before writing a macro:

1. do I need to transform code before evaluation?
2. or do I just need reusable runtime behavior?

If the answer is the second one, write a function.

Knowledge Check