mirror of
https://github.com/penpot/penpot.git
synced 2026-11-20 09:00:49 +00:00
Default is now no `!` for new functions. Existing `!` stays as legacy until its gradual refactor. Allowed cases live in clojure/idioms: mutating public app.db API and functions working over transients. Any further case must be registered there first. AI-assisted-by: muse-spark-1.3-contributor
2.2 KiB
2.2 KiB
Clojure Design Rules
How to shape a function in this codebase. Each rule came from a review round; do not re-derive from taste.
- Preconditions belong to the boundary, not to the core. A function documents what it needs (hints, docstring) and assumes it. Absence checks live where the value enters the system: the caller that resolves optional objects,
ig/init-key, the request handler. A(when (and (some? a) (some? b)) ...)inside a leaf function means the guard is in the wrong place — if you cannot getaorb, you should not be calling it. - Optional-by-design data is guarded where the optionality is born. Example:
ConnectorStatisticsis nil when the server option is off, so the guard iswhen-let [cs (some-> server ...)]at the entry point and the consumer assumescs. - A static set of operations is written statically. With a fixed, small set (four metrics) write the four calls. Do not build a collection and iterate it (
doseqover a literal vector): it allocates, adds indirection and hides each operation. Use a collection when the set is dynamic (config, registry, input). - Default to no
!; existing!is legacy being removed gradually. Do not introduce new!names except the allowed cases documented inmem:clojure/idioms(add and justify the special case there first). Allowed: mutating public fns inapp.db(insert!,update!,delete!,run!,tx-run!, ...) and fns whose contract is to work over transients (stdlibconj!/assoc!/dissoc!/persistent!and custom helpers over them). Existing!elsewhere (e.g.emit!,send!,submit!,validate-file!) stays until its refactor; keep a family consistent in the meantime. Reporting helpers (log, sample-and-publish) never take!: the mutation happens in the!API they call. - Do not shape production code for tests. No return values added just to assert them; assert on the observable effect. When preconditions move, move the tests with them.
Reference implementation: the http metrics samplers in app.http (sample-worker-metrics / sample-connector-metrics are guard-free; sample-http-metrics guards at the boundary).
See also: mem:clojure/idioms (language behaviors), mem:testing (TDD and test conventions).