clojure / clojure/clojure-site
Spec guide improvement - update to include example use cases and anti-patterns of simple namespaces.
@puredanger is already working on this.
Since Apr 6, 2021.
- Dominant language
- HTML
- Stars
- 259
- Forks
- 275
- PR merge metrics
- No merged PRs in 30d
Description
In practice (on blogs and in app templates) application domains are often modeled using simple namespace names instead of globally unique names - task instead of com.myorg.myapp.task.
This is great for getting started for new programmers but if your intention is to construct a scalable application that needs to deal with changing data designs over time, having those globally unique namespaces is crucial, as the rationale indicates.
It would be great if the spec guide had a section detailing this issue and examples of why it is a bad idea to use simple names.
One use case is when a data model has differing semantics on the client versus when being persisted to a database.
Here is an example use case I think would be beneficial in the guide (or a similar one, if not this exact code):
I have a task that has a description which in a UI form is allowed to be an empty string, but when persisted to a database must have a minimum length.
With simple namespace names this is not possible to model in spec:
(s/def :task/description string?)
;; the name is taken already so I can only provide one meaning.
It would be useful to indicate that this is by design of spec and means you are not using the tool as intended.
To alleviate this problem, one solution is to use a fully qualified namespace name:
(s/def :com.myorg.myapp.ui.task/description string?)
(s/def :com.myorg.myapp.db.task/description (s/and string? #(> (count %) 99))))
The spec guide also includes these simple namespace names in some places (:animal, :event) which I think helps encourage the notion that this is a good idea, even though it is directly against the rationale: https://clojure.org/about/spec#_global_namespaced_names_are_more_important
If these simple names are kept in the guide it would be very helpful to those learning spec to call out that this is an anti-pattern for actual usage (I would argue these examples should be removed and use fully qualified global names to avoid any ambiguity that this is a good idea).
Because there is no comment in the guide on the use of these names, and how they should be discouraged, it is very confusing to users when later they find out that this is not how spec is intended to be used.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.