clojure-style

Clojure Style

Guiding principle

Perfection is attained not when there is nothing more to add, but when there is nothing left to take away (Saint-Exupéry). When improving code, look for something to remove before adding anything. Prefer the smallest diff that does the job: surgical edits, clean and lean git history, no drive-by refactors of the surrounding namespace.

Compose small functions

Model the code on the Clojure standard library: many small, single-purpose functions with an obvious data-in/data-out contract, combined through composition rather than accumulated into large bodies.

• Build features by composing existing vars — threading (->, ->>), comp, partial, seq functions — before writing new ones.
• If a function needs internal section comments or does two describable things, split it. A helper with a good name beats a comment.
• Prefer map/filter/reduce/into over explicit loop/recur; reach for loop only when the seq library genuinely doesn't fit.
• Keep the core pure; push side effects to the edges and mark them with !.
• Use a transducer (comp of xforms with into) when a pipeline is reused or performance-critical; otherwise plain threading reads better.

;; prefer
(->> documents
     (filter valid?)
     (map normalize)
     (group-by :category))

Name like clojure.core

Consistency with the standard library and with the surrounding namespace beats novelty. A reader who knows clojure.core should be able to guess what a name means.

• Conventional parameter names: f, g, pred, coll, xs, x, s, m, k, v, n, acc, opts — and project conventions like conn, ident. Match the parameter names already used by sibling functions.
• Systematic affixes: ->tokenizer-xf (constructor), node->hiccup (transform, arrow shows direction), persist-results! (side effect), valid? (predicate), -xf (transducer).
• Simple verbs for transforms (keywordize), plural nouns for extraction (attribute-objects).
• Namespaces: reverse-domain (dk.cst.project-name), kebab-case, a real docstring on the ns form, requires grouped logically (core libraries first), standard aliases (str, walk, io, json).