Use Documentation Practices to compare familiar Java design-pattern habits with smaller Clojure shapes built from data, functions, namespaces, protocols, and explicit boundaries.
This section turns Documentation Practices into concrete design checkpoints for Java engineers moving toward idiomatic Clojure. Treat the child pages as refactoring lenses: keep the useful design intent, then choose the smallest Clojure mechanism that makes the boundary explicit.
| Checkpoint | Java instinct to question | Clojure move to practice |
|---|---|---|
| Representation | Introduce a class, interface, or pattern role before the data shape is clear | Start with immutable data and named transformations |
| Extension | Add hierarchy, listeners, factories, or wrappers for variation | Use functions, maps, protocols, multimethods, or namespaces at explicit seams |
| Effects | Hide I/O, state, or lifecycle behind object identity | Push effects to narrow edges and keep the core easy to test at the REPL |
Work through these pages in order when refactoring an existing Java design. For new Clojure code, start with the simplest data flow that passes tests; add abstraction only when call sites repeat the same boundary.