GaiwanStack/ClojureConventions.md
... ...
@@ -0,0 +1,24 @@
1
+# Gaiwan's Clojure Conventions
2
+
3
+## Project Structure
4
+
5
+- We use Clojure CLI / `deps.edn`
6
+- `src` is for source files, Clojure and ClojureScript or cljc
7
+- The main namespace has at least two segments, an org name and a project name, so `src/org_name/project_name.clj`
8
+- Optionally but recommended, use a reverse domain name for the org name, so you get a (at least) 3-segment name, e.g. `co.gaiwan.our-app`
9
+- This main namespace has a `-main` function that uses [lambdaisland/cli](https://github.com/lambdaisland/cli)
10
+- Other namespaces in the project are prefixed with the org+project name, e.g. `co.gaiwan.our-app.some-ns`, in other words all other source files go under `src/org_name/project_name/`
11
+- The following will refer to `org-name.project-name` as `prefix`
12
+- `resources` is for non-source files that should be accessible on the classpath
13
+- Avoid having files directly inside `resources`, especially with generic names (`config.edn`, `index.html`), because they could easily conflict with other stuff on the classpath. Use `prefix` instead, e.g. `resources/org_name/project_name/config.edn`
14
+- `prefix.config` requires `com.lambdaisland.config`, loads the config, sets the `prefix`, and exposes it to the rest of the app by wrapping the access functions
15
+- Config follows the conventions as described in the [lambdaisland/config](https://github.com/lambdaisland/config) README
16
+
17
+## Tooling
18
+
19
+- We use babashka scripts where applicable
20
+- `bb.edn` should include launchpad and/or lambdaisland/cli
21
+- `bin/dev` is where we create dev tasks, it's a bb script using li/cli
22
+- `bin/launchpad` is a [[WellKnownIdentifier]] that starts launchpad
23
+- `bin/kaocha` is a [[WellKnownIdentifier]] that runs tests
24
+- `*.local.*` and `*.local` are gitignored (`deps.local.edn`, `config.local.edn`, `.env.local`, etc)