将文档字符串放在数据变量上，这被认为是惯用的吗？

Question

所以我定义了一些变量来在我的 clojure 代码中保存状态数据。我刚刚发现我可以向这些变量添加文档字符串，例如：

(def ^{:doc "Documentation for *my-var*"}
        *my-var*)

这让我可以在 REPL 上调用 (doc *my-var*) 。这似乎是一件有效且有用的事情，但在我读过的（有限的）代码中，这似乎并不常见。

这被认为是惯用的 clojure 吗？

Answer 1

从 clojure 1.3 开始，def 允许使用可选的文档字符串。

(def *my-var*
  "My var does cool things (it really doesn't)."
  nil)

Answer 2

也用于 Clojure 命名空间（如 clojure.pprint）：

(def
 ^{:doc "The base to use for printing integers and rationals."
   :added "1.2"}
 *print-base* 10)

您可能不想使用 clojure.contrib.def 中的便捷宏：

(defvar *my-var*
  nil
  "Documentation for *my-var*")