Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Claude.md instructions for docstrings (#74246)

Timothy S. Dean8a36e2964fcc
diff --git a/.claude/skills/clojure-write/SKILL.md b/.claude/skills/clojure-write/SKILL.md
index 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 code
diff --git a/CLAUDE.md b/CLAUDE.md
index 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