Clojure Style and Formatting

Clojure style is not about making Lisp look like Java. It is about making nested forms, immutable values, and namespace-qualified calls easy to scan.

For Java engineers, the biggest adjustment is that formatting carries structure. Braces and type declarations are gone, so indentation, naming, and form shape do more work.

What Good Clojure Style Optimizes For

Style is part of correctness because poorly formatted Clojure hides evaluation order.

Indentation: Follow The Form

Function bodies usually indent two spaces:

1(defn invoice-total [invoice]
2  (+ (:subtotal invoice)
3     (:tax invoice)
4     (- (:discount invoice 0))))

Binding forms align name/value pairs:

1(let [subtotal (:subtotal invoice)
2      tax      (:tax invoice)
3      discount (:discount invoice 0)]
4  (- (+ subtotal tax) discount))

Threaded pipelines indent each step:

1(-> invoice
2    normalize-lines
3    apply-discounts
4    calculate-tax)

Do not fight the formatter. If indentation looks strange, first ask whether the form shape is too complex.

Naming Conventions

Clojure names are usually lowercase and hyphenated:

1(defn normalize-email [email]
2  ...)

Important naming markers:

These markers are compact contracts. They help reviewers notice when code is pure, effectful, conditional, or conversion-oriented.

Avoid Java Naming Drift

Use verbs when the operation matters, but do not force every function into a Java method-name pattern. In Clojure, many functions are best named after the value they return.

Whitespace in Collections

Readable data literals are as important as readable function calls:

1{:user/id     42
2 :user/email  "dev@example.com"
3 :user/roles  #{:admin :billing}
4 :user/status :active}

Use alignment when it helps compare related keys. Do not over-align unrelated data until small changes create noisy diffs.

Commas are whitespace in Clojure:

1[:a, :b, :c]
2;; same as
3[:a :b :c]

Most idiomatic code omits commas except when they materially improve readability in dense literals.

Comments and Blank Lines

Use blank lines to separate ideas, not every expression:

 1(defn billable-lines [invoice]
 2  (->> (:lines invoice)
 3       (filter billable?)
 4       (map apply-discount)))
 5
 6(defn invoice-total [invoice]
 7  (->> invoice
 8       billable-lines
 9       (map :line/total-cents)
10       (reduce + 0)))

Keep comments for intent and tradeoffs. If a comment only explains parentheses, improve the code shape instead.

Formatter Workflow

Use a formatter such as cljfmt through the build tool your project already uses. The exact command depends on the project, but the review rule is stable:

Avoid pinning old dependency snippets in learning material unless you are showing a real project file. Tool versions change; the habit matters more here than a stale version number.

Refactoring For Readability

Bad formatting often signals too much work in one form:

1(defn total-active-cents [users]
2  (reduce + (map :balance-cents (filter (fn [user] (= :active (:status user))) users))))

Prefer a pipeline with named steps when that helps the reader:

1(defn total-active-cents [users]
2  (->> users
3       (filter active-user?)
4       (map :balance-cents)
5       (reduce + 0)))

This is not merely prettier. It makes the data flow reviewable.

Practice

1. Rename getUserById, isPaid, and saveInvoice into idiomatic Clojure names.
2. Reformat a dense let so bindings are easy to scan.
3. Rewrite a nested map/filter/reduce expression into a ->> pipeline.
4. Decide whether a function name should end with ? or !.

Key Takeaways

• Clojure formatting should reveal form structure and data flow.
• Use kebab-case names, ? for predicates, ! for effectful operations, and -> for conversions.
• Prefer small, readable forms over clever one-liners.
• Let formatters reduce whitespace debates, but still refactor when formatting exposes complexity.
• Do not import Java camelCase and method-naming habits into idiomatic Clojure.

Quiz: Clojure Style and Formatting