Clojure

Clojure Development Instructions

Code Evaluation Tool usage

“Use the repl” means to use the Evaluate Clojure Code tool from Calva Backseat Driver. It connects you to the same REPL as the user is connected to via Calva.

• Always stay inside Calva's REPL instead of launching a second one from the terminal.
• If there is no REPL connection, ask the user to connect the REPL instead of trying to start and connect it yourself.

JSON Strings in REPL Tool Calls

Do not over-escape JSON arguments when invoking REPL tools.

{
  "namespace": "<current-namespace>",
  "replSessionKey": "cljs",
  "code": "(def foo \"something something\")"
}

Docstrings in defn

Docstrings belong immediately after the function name and before the argument vector.

(defn my-function
  "This function does something."
  [arg1 arg2]
  ;; function body
  )

• Define functions before they are used—prefer ordering over declare except when truly necessary.

Interactive Programming (a.k.a. REPL Driven Development)

Align Data Structure Elements for Bracket Balancing

Always align multi-line elements vertically in all data structures: vectors, maps, lists, sets, all code (since Clojure code is data). Misalignment causes the bracket balancer to close brackets incorrectly, creating invalid forms.

;; ❌ Wrong - misaligned vector elements
(select-keys m [:key-a
                :key-b
               :key-c])  ; Misalignment → incorrect ] placement

;; ✅ Correct - aligned vector elements
(select-keys m [:key-a
                :key-b
                :key-c])  ; Proper alignment → correct ] placement

;; ❌ Wrong - misaligned map entries
{:name "Alice"
 :age 30
:city "Oslo"}  ; Misalignment → incorrect } placement

;; ✅ Correct - aligned map entries
{:name "Alice"
 :age 30
 :city "Oslo"}  ; Proper alignment → correct } placement

Critical: The bracket balancer relies on consistent indentation to determine structure.

REPL Dependency Management

Use clojure.repl.deps/add-libs for dynamic dependency loading during REPL sessions.

(require '[clojure.repl.deps :refer [add-libs]])
(add-libs '{dk.ative/docjure {:mvn/version "1.15.0"}})

• Dynamic dependency loading requires Clojure 1.12 or later
• Perfect for library exploration and prototyping

Checking Clojure Version

*clojure-version*
;; => {:major 1, :minor 12, :incremental 1, :qualifier nil}

REPL Availability Discipline

Never edit code files when the REPL is unavailable. When REPL evaluation returns errors indicating that the REPL is unavailable, stop immediately and inform the user. Let the user restore REPL before continuing.

Why This Matters

• Interactive Programming requires a working REPL - You cannot verify behavior without evaluation
• Guessing creates bugs - Code changes without testing introduce errors

Structural Editing and REPL-First Habit

• Develop changes in the REPL before touching files.
• When editing Clojure files, always use structural editing tools such as Insert Top Level Form, Replace Top Level Form, Create Clojure File, and Append Code, and always read their instructions first.

Creating New Files

• Use the Create Clojure File tool with initial content
• Follow Clojure naming rules: namespaces in kebab-case, file paths in matching snake_case (e.g., my.project.ns → my/project/ns.clj).

Reloading Namespaces

After editing files, reload the edited namespace in the REPL so updated definitions are active.

(require 'my.namespace :reload)

Code Indentation Before Evaluation

Consistent indentation is crucial to help the bracket balancer.

;; ❌
(defn my-function [x]
(+ x 2))

;; ✅
(defn my-function [x]
  (+ x 2))

Indentation preferences

Keep the condition and body on separate lines:

(when limit
  (println "Limit set to:" limit))

Keep the and and or arguments on separate lines:

(if (and condition-a
         condition-b)
  this
  that)

Inline Def Pattern

Prefer inline def debugging over println/console.log.

Inline def for Debugging

• Inline def bindings keep intermediate state inspectable during REPL work.
• Leave inline bindings in place when they continue to aid exploration.

(defn process-instructions [instructions]
  (def instructions instructions)
  (let [grouped (group-by :status instructions)]
    grouped))

• Real-time inspection stays available.
• Debugging cycles stay fast.
• Iterative development remains smooth.

You can also use "inline def" when showing the user code in the chat, to make it easy for the user to experiment with the code from within the code blocks. The user can use Calva to evaluate the code directly in your code blocks. (But the user can't edit the code there.)

Return values > print side effects

Prefer using the REPL and return values from your evaluations, over printing things to stdout.

Reading from stdin

• When Clojure code uses (read-line), it will prompt the user through VS Code.
• Avoid stdin reads in Babashka's nREPL because it lacks stdin support.
• Ask the user to restart the REPL if it blocks.

Data Structure Preferences

We try to keep our data structures as flat as possible, leaning heavily on namespaced keywords and optimizing for easy destructuring. Generally in the app we use namespaced keywords, and most often "synthetic" namespaces.

Destructure keys directly in the parameter list.

(defn handle-user-request
  [{:user/keys [id name email]
    :request/keys [method path headers]
    :config/keys [timeout debug?]}]
  (when debug?
    (println "Processing" method path "for" name)))

Among many benefits this keeps function signatures transparent.

Avoid Shadowing Built-ins

Rename incoming keys when necessary to avoid hiding core functions.

(defn create-item
  [{:prompt-sync.file/keys [path uri]
    file-name :prompt-sync.file/name
    file-type :prompt-sync.file/type}]
  #js {:label file-name
       :type file-type})

Common symbols to keep free:

• class
• count
• empty?
• filter
• first
• get
• key
• keyword
• map
• merge
• name
• reduce
• rest
• set
• str
• symbol
• type
• update

Avoid Unnecessary Wrapper Functions

Do not wrap core functions unless a name genuinely clarifies composition.

(remove (set exclusions) items) ; a wrapper function would not make this clearer

Rich Comment Forms (RCF) for Documentation

Rich Comment Forms (comment ...) serve a different purpose than direct REPL evaluation. Use RCFs in file editing to document usage patterns and examples for functions you've already validated in the REPL.

When to Use RCFs

• After REPL validation - Document working examples in files
• Usage documentation - Show how functions are intended to be used
• Exploration preservation - Keep useful REPL discoveries in the codebase
• Example scenarios - Demonstrate edge cases and typical usage

RCF Patterns

RCF = Rich Comment Forms.

When files are loaded code in RCFs is not evaluated, making them perfect for documenting example usage, since humans easily can evaluate the code in there at will.

(defn process-user-data
  "Processes user data with validation"
  [{:user/keys [name email] :as user-data}]
  ;; implementation here
  )

(comment
  ;; Basic usage
  (process-user-data {:user/name "John" :user/email "john@example.com"})

  ;; Edge case - missing email
  (process-user-data {:user/name "Jane"})

  ;; Integration example
  (->> users
       (map process-user-data)
       (filter :valid?))

  :rcf) ; Optional marker for end of comment block

RCF vs REPL Tool Usage

;; In chat - show direct REPL evaluation:
(in-ns 'my.namespace)
(let [test-data {:user/name "example"}]
  (process-user-data test-data))

;; In files - document with RCF:
(comment
  (process-user-data {:user/name "example"})
  :rcf)

Testing

Run Tests from the REPL

Reload the target namespace and execute tests from the REPL for immediate feedback.

(require '[my.project.some-test] :reload)
(clojure.test/run-tests 'my.project.some-test)
(cljs.test/run-tests 'my.project.some-test)

• Tighter REPL integration.
• Focused execution.
• Simpler debugging.
• Direct access to test data.

Prefer running individual test vars from within the test namespace when investigating failures.

Use REPL-First TDD Workflow

Iterate with real data before editing files.

(def sample-text "line 1\nline 2\nline 3\nline 4\nline 5")

(defn format-line-number [n padding marker-len]
  (let [num-str (str n)
        total-padding (- padding marker-len)]
    (str (apply str (repeat (- total-padding (count num-str)) " "))
         num-str)))

(deftest line-number-formatting
  (is (= "  5" (editor-util/format-line-number 5 3 0))
      "Single digit with padding 3, no marker space")
  (is (= " 42" (editor-util/format-line-number 42 3 0))
      "Double digit with padding 3, no marker space"))

Benefits

• Verified behavior before committing changes
• Incremental development with immediate feedback
• Tests that capture known-good behavior
• Start new work with failing tests to lock in intent

Test Naming and Messaging

Keep deftest names descriptive (area/thing style) without redundant -test suffixes.

Test Assertion Message Style

Attach expectation messages directly to is, using testing blocks only when grouping multiple related assertions.

(deftest line-marker-formatting
  (is (= "→" (editor-util/format-line-marker true))
      "Target line gets marker")
  (is (= "" (editor-util/format-line-marker false))
      "Non-target gets empty string"))

(deftest context-line-extraction
  (testing "Centered context extraction"
    (let [result (editor-util/get-context-lines "line 1\nline 2\nline 3" 2 3)]
      (is (= 3 (count (str/split-lines result)))
          "Should have 3 lines")
      (is (str/includes? result "→")
          "Should have marker"))))

Guidelines:

• Keep assertion messages explicit about expectations.
• Use testing for grouping related checks.
• Maintain kebab-case names like line-marker-formatting or context-line-extraction.

Happy Interactive Programming

Remember to prefer the REPL in your work. Keep in mind that the user does not see what you evaluate. Nor the results. Communicate with the user in the chat about what you evaluate and what you get back.