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
Claude.md instructions for docstrings (#74246)
Timothy S. Dean8a36e2964fcc
diff --git a/.claude/skills/clojure-write/SKILL.md b/.claude/skills/clojure-write/SKILL.mdindex 17b665f7927..350cca74658 100644--- a/.claude/skills/clojure-write/SKILL.md+++ b/.claude/skills/clojure-write/SKILL.md@@ -60,6 +60,41 @@ Only fall back to `./bin/mage` commands when clojure-mcp is not available.Feel free to copy these REPL session trials into actual test cases using `deftest` and `is`.4. Once you know these functions are good, return to 1, and compose them into the task that you need to build.+## Writing Docstrings++A docstring is a contract for the *caller*, not a diary for the+implementer. It states what the function does, what it takes, returns,+throws, and the preconditions/invariants the caller must respect. Those+guarantees and requirements *belong* there — they are exactly what the+caller needs surfaced in the IDE.++When you find implementation context in a docstring, the default is to+**relocate it, not delete it** — move it to an inline comment at the+point in the body where it is actually relevant. That context is often+genuinely valuable; it is just in the wrong place (the caller should not+have to read it; the implementer standing at that line should). Delete+outright only when it is blather: self-congratulation, restating the+obvious, or documenting a property that is the expected default.++On that last case — narrating properties like "portable across all+supported appdbs" earns no sentence. If it were not portable, that is+either a bug, or it means callers must handle each case themselves — and+in *that* case it is the *absence* of the property that must be+documented. Document deviations from expectation, not conformance to it.++Heuristic: if a sentence would still be true after a full rewrite of the+body, it may belong in the docstring. If it describes *how the current+body works*, it belongs in the body — as an inline comment, if it is+non-obvious.++Multi-line docstrings are not banned — a genuinely non-obvious constraint+the code had to deal with can be worth explaining. But be prudent; the+failure mode is far too much detail. When tempted to write a+multi-paragraph explanatory docstring, check with the user first. And+prefer a *test* to prose: if a future reader thinks "that's a silly way+to do it" and changes it, a test should fail and tell them why. If that+breakage keeps happening, *that* is the signal a comment was warranted.+## Critical Rules for Editing- Be careful with parentheses counts when editing Clojure codediff --git a/CLAUDE.md b/CLAUDE.mdindex cb31a36895b..22cdee4d79e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -60,4 +60,4 @@ Once again, do not use `clj -X:dev:test` directly — its progress-bar output is## Tool Preferences-If `clojure-mcp` tools are available, prefer them over shell-based alternatives for Clojure development.+If `clojure-mcp` tools are available, prefer them over shell-based alternatives for Clojure development.\ No newline at end of file