The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Update Claude Clojure style guide (#85881)
Cam Saul037141bb2a02
diff --git a/.claude/skills/_shared/clojure-style-guide.md b/.claude/skills/_shared/clojure-style-guide.mdindex 94c7e4306e6..60d58e11e99 100644--- a/.claude/skills/_shared/clojure-style-guide.md+++ b/.claude/skills/_shared/clojure-style-guide.md@@ -25,7 +25,10 @@ This guide covers Clojure and ClojureScript coding conventions for Metabase. See- Every public var in `src` or `enterprise/backend/src` must have docstring- Format using Markdown conventions-- Reference other vars with `[[other-var]]` not backticks+- Refer to a namespace or var as a link, `[[metabase.util.json/decode]]` or `[[metabase.sql-parsing.core]]`, never in+ backticks: the brackets tell tooling it is a real namespace or var, so it can be resolved and linked. An+ alias-qualified `[[sql/unsupported]]` or an unqualified `[[decode-manifest]]` works too. Backticks are for everything+ else: keys, literals, SQL, file names, shell commands.A docstring states the *contract*: what it returns (including when it returns nil), what itsparams mean, what it throws versus swallows, and any precondition or invariant the caller must@@ -79,6 +82,20 @@ These seven things are, and each is a reason to cut or relocate:Use `ex-cause`/`ex-message`/`ex-data`/`ex-info` rather than `.getCause`/`.getMessage`/`(.getData ^ExceptionInfo …)` where possible.+**`(set! *warn-on-reflection* true)` goes in a file only when that file does Java interop:**++Add it after the `ns` form when the file has `.method` calls, `Class/staticMethod` calls, constructors or used+`:import`s, so the compiler reports any call it has to resolve by reflection. A file with no interop does not get the+line, whatever its neighbours do: nine sibling files that use interop say nothing about a tenth that does not. Add it+when interop is added later.++In a `.cljc` file the same rule applies to the JVM-only code: when a `#?(:clj …)` or `#?@(:clj …)` branch does Java+interop, the file gets the line, itself inside a reader conditional:++```clojure+#?(:clj (set! *warn-on-reflection* true))+```+## Style Conventions**Keywords and Metadata:**@@ -103,6 +120,73 @@ Use `ex-cause`/`ex-message`/`ex-data`/`ex-info` rather than `.getCause`/`.getMesOnly `(:import java.time.X)` when interop with a Java method genuinely needs the class.+**A branch that yields `nil` is a `when` or `when-not`, not an `if` with a `nil` arm:**++```clojure+;; good+(when-not (= agg :count)+ (unsupported "%s over * has no Metabase equivalent" (name agg)))++;; bad+(if (= agg :count)+ nil+ (unsupported "%s over * has no Metabase equivalent" (name agg)))+```++The same goes for `(if c x nil)`: write `(when c x)`.++**A local binding never shadows a `clojure.core` var or a var in the current namespace:**++```clojure+;; good+(defn field-metadata [field-name field-base-type] ...)+(let [{entity-type :type} entity] ...)++;; bad+(defn field-metadata [name base-type] ...) ; `name` is clojure.core/name; `base-type` is a fn in this ns+(let [{:keys [type]} entity] ...) ; `type` is clojure.core/type+```++Qualify the name instead: `field-name`, `entity-type`, `table-alias`, `unsupported-metrics`. Watch `:keys`+destructuring in particular, since it names the local after the key. kondo's `:shadowed-var` linter finds these.++**An ID takes its entity's ID schema, never a general one like `pos-int?`:**++```clojure+;; good+(mu/defn table-ref [table-id :- ::lib.schema.id/table] ...)++;; bad+(mu/defn table-ref [table-id :- pos-int?] ...)+```++`metabase.lib.schema.id` has a schema for every entity with an ID (`::lib.schema.id/database`, `::table`, `::field`,+`::card`, ...). Some modules define their own equivalents for their entities; those are fine to use instead.++**A no-argument function passed around is a `thunk`, not an `f`:**++```clojure+;; good+(defn with-context [context thunk]+ (thunk))++;; bad+(defn with-context [context f]+ (f))+```++**Find one element with `m/find-first`, not `(first (filter ...))`:**++```clojure+;; good+(m/find-first #(= metric-name (:name %)) metrics)++;; bad+(first (filter #(= metric-name (:name %)) metrics))+```++`medley.core` is aliased as `m`. It says what is meant.+**Check non-emptiness with `seq`, not `count`:**```clojure@@ -530,7 +614,7 @@ Other useful map ops:- **`(:import (java.time …))` + `(LocalDate/now)`** in new code — use `[java-time.api :as t]` + `[metabase.util.date-2 :as u.date]`. Direct `java.time` interop only when a Java API genuinely needs the class.- **Vanilla `defmethod`** — use `methodical/defmethod` (it takes a docstring; the codebase uses it uniformly).- **`(when (premium/has-feature? :flag) …)` in code** — gate via `defenterprise` so OSS/EE bodies live in their respective namespaces; never sprinkle runtime feature checks.-- **No `(set! *warn-on-reflection* true)` after the `ns` form** in a new `.clj` file — every `.clj` source file in this repo has it (not `.cljc`).+- **`(set! *warn-on-reflection* true)` missing from a file that does Java interop, or present in one that does not** — the line is there to surface reflective calls, so it follows the interop, not the convention of neighbouring files. In `.cljc`, it is `#?(:clj (set! *warn-on-reflection* true))` when a `:clj` branch does interop. See the `*warn-on-reflection*` paragraph under "Code Organization".- **`(ns … (:require [a :as a] [b :as b]))` on one line; `(:import java.io.File java.net.URI)` bare** — both wrong shapes. Requires one per line under `:require`, imports as `(Package Class)` lists.- **Inventing a fresh `:as` alias for `metabase.util`, `metabase.util.malli`, `metabase.util.log`, `java-time.api`, etc.** — use the canonical alias (see the table in Style Conventions). Mixing aliases makes `grep`-based discovery worse.- **`(def Foo [:map …])` for a Malli schema** — `(mr/def ::foo "doc" [:map …])` and reference it as `::foo`, even in `dev/`. See "Schemas".