Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposal for #245 #246

Merged
merged 2 commits into from
Oct 17, 2022
Merged

proposal for #245 #246

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c492e8e
proposal for #245
seancorfield Oct 15, 2022
c7504e6
add clojure.core.protocols -> P
seancorfield Oct 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 42 additions & 15 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -768,40 +768,66 @@ NOTE: This may appear to mask
(string/join ...)
----

Some common, idiomatic aliases are shown below:
As noted in the next section, it's generally considered idiomatic to use
an alias that is the last segment of the namespace, if that makes it unique,
or else the two segments, typically dropping redundant parts like `clj` or `core`.

Amongst Clojure's core and Contrib namespaces, the following namespaces have
idiomatic aliases following that pattern:

|===
| Namespace | Idiomatic Alias
| clojure.datafy
| datafy
| clojure.edn
| edn
| clojure.java.io
| io
| clojure.java.shell
| sh
| clojure.math
| math
| clojure.pprint
| pp
| clojure.set
| set
| clojure.spec.alpha
| spec
| clojure.string
| str
| clojure.walk
| walk
| clojure.zip
| zip
| clojure.core.async
| as
| clojure.core.matrix
| mat
| async
| clojure.data.csv
| csv
| clojure.data.xml
| xml
| clojure.tools.cli
| cli
|===

Then there are some core and Contrib namespaces that have shorter idiomatic aliases:

|===
| Namespace | Idiomatic Alias
| clojure.java.shell
| sh
| clojure.pprint
| pp
| clojure.spec.alpha
| s
| clojure.string
| str
| clojure.core.matrix
| mat
| clojure.tools.logging
| log
| clojure.core.protocols
| p
| clojure.core.reducers
| r
|===

And amongst commonly used community libraries, there are also many that have
widely-used, idiomatic aliases for several namespaces:

|===
| Namespace | Idiomatic Alias
| cheshire.core
| json
| clj-yaml.core
Expand All @@ -812,6 +838,8 @@ Some common, idiomatic aliases are shown below:
| sql
| java-time
| time
| next.jdbc
| jdbc
|===

=== A Recipe for Good Namespace Aliases
Expand All @@ -822,7 +850,7 @@ You might have noticed that those are a bit inconsistent:
* `clojure.string` becomes `str`
* `clojure.pprint` becomes `pp`
* `clojure.walk` becomes `walk`
* `clojure.spec.alpha` becomes `spec`
* `clojure.spec.alpha` becomes `s`

It's clear that the one thing they have in common is that they aim to be concise, but still carry some meaning (aliasing `clojure.walk` to `w` would
be concise, but won't carry much meaning).
Expand All @@ -837,7 +865,7 @@ otherwise the people working on a shared Clojure codebase are going to experienc
(ns com.example.application
(:require
[clojure.java.io :as io]
[clojure.string :as string]))
[clojure.reflect :as reflect]))
----

2. Keep enough trailing parts to make each alias unique.
Expand All @@ -854,7 +882,6 @@ TIP: Yes, namespace aliases can have dots in them. Make good use of them.

[source,clojure]
----
[clj-http :as http]
[clj-time.core :as time]
[clj-time.format :as time.format]
----
Expand Down