Why meta-data map is declared before symbol?

Question

This is a stylistic thing, and I’m trying to understand design decision. It feels intuitive to attach metadata after the symbol since it naturally reads as: “define User, with metadata X.” But in Clojure, metadata appears before the symbol, why?

Clojure:
(def ^{:doc “doctoring”} user-id (uuid))
(defn ^{:doc “doctoring”} create-user [email] (db/create-user email)

As opposed to:
(def user-id ^{:doc “doctoring”} (uuid))
(defn create-user ^{:doc “doctoring”} [email] (db/create-user email)

Is it for parsing simplicity of the reader? Attach this meta to the next symbol?

Answer 1

Don't know if there is some reason. I do think it's easier for the reader (defined in one place and does not require state), but could probably have been done the other way too.

Originally there was no syntax for it and (per Common Lisp / CLOS), and you would just

(with-meta [1 2 3] {:tag :xyz})

As a special case, the defn macro does actually support optional metadata at the end of multi-arity syntax (although this is rarely used):

(defn create-user ([email] (db/create-user email)) {:doc “doctoring”})

Answer 2

I'd answer that the documentation is about the var (the symbol), not about the value.

The usage is (-> #'user-id meta :doc), and not (-> user-id meta :doc).

This is how my mental model works.