Skip to content

Commit 1f0c020

Browse files
committed
[#201] Add a recipe for good namespace aliases
1 parent d93c91e commit 1f0c020

File tree

1 file changed

+47
-0
lines changed

1 file changed

+47
-0
lines changed

README.adoc

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -679,9 +679,56 @@ Bellow are some common idiomatic aliases:
679679
| clojure.java.shell
680680
|===
681681

682+
=== A Recipe for Good Namespace Aliases
683+
684+
Above we covered a handful of popular namespaces and their idiomatic aliases.
685+
You might have noticed that those are a bit inconsistent:
686+
687+
* `clojure.string` becomes `str`
688+
* `clojure.pprint` becomes `pp`
689+
* `clojure.walk` becomes `walk`
690+
* `clojure.spec.alpha` becomes `spec`
691+
692+
I guess 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
693+
be concise, but won't carry much meaning).
694+
695+
But what to do about all the other namespaces out there that don't have idiomatic aliases? Well, you better be consistent in your approach to deriving aliases for them,
696+
otherwise the people working on a shared Clojure codebase are going to experience a great deal of confusion. Here are a few rules that you should follow.footnote:[These guidelines are based on a https://stuartsierra.com/2015/05/10/clojure-namespace-aliases[blog post] by Stuart Sierra.]
697+
698+
. Make the alias the same as the namespace name with the leading parts removed.
699+
700+
[source,clojure]
701+
----
702+
(ns com.example.application
703+
(:require
704+
[clojure.java.io :as io]
705+
[clojure.string :as string]))
706+
----
707+
708+
. Keep enough trailing parts to make each alias unique.
709+
710+
[source,clojure]
711+
----
712+
[clojure.data.xml :as data.xml]
713+
[clojure.xml :as xml]
714+
----
715+
716+
TIP: Yes, namespace aliases can have dots in them. Make good use of them.
717+
718+
. Eliminate redundant words such as "core" and "clj" in aliases.
719+
720+
[source,clojure]
721+
----
722+
[clj-http :as http]
723+
[clj-time.core :as time]
724+
[clj-time.format :as time.format]
725+
----
726+
682727
=== Use Consistent Namespace Aliases
683728

684729
Across a project, it's good to be consistent with namespace aliases; e.g., don't require `clojure.string` as `str` in one namespace but `string` in another.
730+
If you follow the previous two guidelines you're basically covered, but if you opt for custom namespace aliasing scheme it's still important to apply it
731+
consistently within your projects.
685732

686733
== Functions
687734

0 commit comments

Comments
 (0)