Spec guide improvement - update to include example use cases and anti-patterns of simple namespaces.
@puredanger がすでに取り組んでいます。
2021年4月6日 から。
評価
この issue はまだ評価されていません。
説明
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.
- 主要言語
- HTML
- スター
- 259
- フォーク
- 276
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
clojure/clojure-site のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
clojure/clojure-site#723 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
clojure/clojure-site#538 · コメント 3 件 ·
-
help wanted
難易度 1/5 1時間未満 初心者へのやさしさ 62/100
clojure/clojure-site#386 · コメント 1 件 ·
-
難易度 1/5 1時間未満 初心者へのやさしさ 55/100
clojure/clojure-site#715 ·
-
難易度 5/5 1週間以上 初心者へのやさしさ 25/100
clojure/clojure-site#713 ·