From 8be3fa6f0b9df825db0a77d946ef84520d5fec7c Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Thu, 27 Aug 2026 22:41:56 +0200 Subject: [PATCH] docs: how to name modules A module has one declaration site in the whole program, dependencies included, so two packages that both declare mod Cube cannot be used together. Adds the convention Flix libraries follow. --- AGENTS.md | 11 +++++++++++ README.md | 17 ++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 18f688d..59e9b45 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,3 +65,14 @@ The mistakes that show up most often: Prefer effects and handlers to callbacks or hand-written CPS, and standard library effects to Java interop. + +## Naming modules + +A module has one declaration site in the whole program, dependencies included, +so never take a common top-level name. + +- one root namespace per package, named after it: `flix-json` roots at `Json` +- directories mirror module paths: `Json.FromJson` in `src/Json/FromJson.flix` +- two or three levels; `Internal` for what is not API +- name a module for what is done there: `Json.Parse` holds `parse` +- spell names out; tests flat, one `TestX` per subject diff --git a/README.md b/README.md index edc2b32..a40f251 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,20 @@ allowed to differ — any pin at or above the floor satisfies it — but `./flixw validate` fails when the pin does not, so the two cannot drift apart unnoticed. +## Naming what you add + +A module has one declaration site in the whole program, dependencies included: +two packages that both declare `mod Cube` cannot be used together. What Flix +libraries do: + +- one root namespace, named after the package: `flix-json` roots at `Json`, + `flix-basicdb` at `BasicDB` +- directories mirror module paths: `Json.FromJson` lives in + `src/Json/FromJson.flix` +- two or three levels; `Internal` for what is not API +- modules named for what you do there: `Json.Parse` holds `parse` +- names spelled out, and tests flat: one `TestX` per subject + ## What the wrapper is and is not `flixw` never patches, forks or links against the Flix compiler. It fetches the @@ -125,7 +139,8 @@ warns rather than failing, so a fresh copy of this template does not start red. 1. `flix.toml` — set `name`, `description`, `version` and `authors`. The package name is yours to choose; nothing requires it to match the repository name. 2. `LICENSE` — replace the copyright line, or the whole license. -3. `src/` and `test/` — replace the greeting with your own code. +3. `src/` and `test/` — replace the greeting with your own code, minding + [Naming what you add](#naming-what-you-add). 4. This README — the badge URLs and the documentation link. Until you point them at your own repository they report this one's state, not yours. CI fails on the first push until you do, and names every URL still pointing