|
| 1 | +--- |
| 2 | +description: 'Things agents tend to forget or get wrong when they are working with Clojure projects.' |
| 3 | +applyTo: '**/*.clj*,**/*.bb' |
| 4 | +--- |
| 5 | + |
| 6 | +# Clojure Memory |
| 7 | + |
| 8 | +## Docstring placement in function definitions (`defn`) |
| 9 | + |
| 10 | +The docstring goes after the symbol/function name, and before the argument vector. |
| 11 | + |
| 12 | +### ❌ Incorrect: |
| 13 | +```clojure |
| 14 | +(defn my-function |
| 15 | + [arg1 arg2] |
| 16 | + "This function does something." |
| 17 | + ;; function body |
| 18 | + ) |
| 19 | +``` |
| 20 | + |
| 21 | +### ✅ Correct: |
| 22 | +```clojure |
| 23 | +(defn my-function |
| 24 | + "This function does something." |
| 25 | + [arg1 arg2] |
| 26 | + ;; function body |
| 27 | + ) |
| 28 | +``` |
| 29 | + |
| 30 | +## Editing Clojure files |
| 31 | + |
| 32 | +Remember to develop solutions in the repl before editing files. However, even as an interactive programmer, now and then you do edit files. And when you do, you use structural editing tools, like `replace_top_level_form`, and `insert_top_level_form`. **Always read the instructions for these tools before using them**. If you are appending to a file, use the built in editing tool. |
| 33 | + |
| 34 | +### Define functions before using them |
| 35 | + |
| 36 | +The Clojure compiler needs functions to be defined before they are used. Prefer placing functions in the correct order over using `declare` (which is sometimes necessary, but most often `declare` is just cheating). |
| 37 | + |
| 38 | +## Creating Clojure files |
| 39 | + |
| 40 | +Use the `create_file` tool to create files with empty content `""`. |
| 41 | + |
| 42 | +#### Clojure Namespace and Filename Convention: |
| 43 | + |
| 44 | +**Important**: In Clojure, namespace names use kebab-case while filenames use snake_case. For example: |
| 45 | +- Namespace: `my.project.multi-word-namespace` |
| 46 | +- Filename: `my/project/multi_word_namespace.clj(s|c)` |
| 47 | + |
| 48 | +Always convert dashes in namespace names to underscores in the corresponding filename. |
| 49 | + |
| 50 | +### Create empty files, then add content |
| 51 | + |
| 52 | +For you to create files and add content safely/predictably, follow this process: |
| 53 | + |
| 54 | +1. **Always create empty files first** - Use `create_file` with empty content `""` |
| 55 | +2. Read the content of the file created (default content may have been added) |
| 56 | +3. **Use structural editing tools** to edit the file |
| 57 | + |
| 58 | +## Namespace Reloading in the REPL |
| 59 | + |
| 60 | +When working in the REPL after editing files, you need to reload namespaces to ensure your changes are reflected in the REPL. |
| 61 | + |
| 62 | +```clojure |
| 63 | +;; Reload just the specified namespace |
| 64 | +(require 'my.namespace :reload) |
| 65 | +``` |
| 66 | + |
| 67 | +## When the bracket balance is off |
| 68 | + |
| 69 | +When you have a situation where e.g. the problem tool or Clojure compiler complains about missing brackets or anything suggesting the bracket balance is off: |
| 70 | +* Instead of going ahead trying to fix it, **use the tool for requesting human input to ask for guidance/help.** |
| 71 | + |
| 72 | +## Reading from stdin |
| 73 | + |
| 74 | +Reading from stdin (e.g. `(read-line)`) will prompt the user with a VS Code input box. Be aware of this when evaluating code that may read from stdin. |
| 75 | + |
| 76 | +### With Babashka, reading from stdin blocks the repl |
| 77 | + |
| 78 | +Babashka's nrepl server does not yet support the stdin protocol. Avoid evaluating code that reads from stdin with the Babashka repl. |
| 79 | + |
| 80 | +**If REPL hangs**: Ask user to restart REPL. |
| 81 | + |
| 82 | +## Happy Interactive Programming |
| 83 | + |
| 84 | +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. |
0 commit comments