每个变量页面上的示例文档旨在提供简单、孤立的变量使用示例。简而言之，你添加到 Clojuredocs 的示例应该易于理解，为了帮助你达到这个目的，我们概述了一些准则，如下所示。
示例应该是简短、独特且自成一体的代码片段，以最简洁的方式展示变量的使用。
如果目标变量不是核心库的一部分（或默认情况下未使用），请包含 use / require 语句。
差
(sh “ls” “-aul”)
;; {:exit 0,
;; :out “total 64
;; drwxr-xr-x 11 zkim staff 374 Jul 5 13:21 .”
;; …
好
(use '[clojure.java.shell :only [sh]])(sh “ls” “-aul”)
;; {:exit 0,
;; :out “total 64
;; drwxr-xr-x 11 zkim staff 374 Jul 5 13:21 .”
…
每个示例应该是宽泛的或深入的，但不能同时两者兼具。例如，以下适用于 not= 的示例展示允许的广泛的输入值。
(not= 1 1) ;;=> false(not= 1 2) ;;=> true
(not= true true) ;;=> false
(not= true false) ;;=> true
(not= true true true true) ;;=> false
(not= true true false true) ;;=> true
而适用于 future 的示例则比较深入。
;; A future is calculated in another thread (def f (future (Thread/sleep 10000) 100)) ;;=> #'user/f;; When you dereference it you will block until the result is available.
@f
;;=> 100;; Dereferencing again will return the already calculated value immediately.
@f
;;=> 100
另外，请提及你认为与你的示例（具体而言）或变量（一般而言）相关的任何要点。
注释应用于描述下面的代码块或指向信息片段，但这些片段可能并不明显给 Clojure 新手开发者。
差
(with-precision 10 (/ 1M 3)) ;;=> 0.3333333333Muser=> (.floatValue 0.3333333333M)
;;=> 0.33333334
好
;; The "M" suffix denotes a BigDecimal instance ;; http://download.oracle.com/javase/6/docs/api/java/math/BigDecimal.html(with-precision 10 (/ 1M 3))
;;=> 0.3333333333M(.floatValue 0.3333333333M)
;;=> 0.33333334
;; 应该是对代码块的一般性注释，; 应该用于在代码行末添加注释。
差
; This function will print 'hello world' to the console (defn hello-world [] (println "hello world")) ;; Does the actual printing
好
;; This function will print 'hello world' to the console (defn hello-world [] (println "hello world")) ; Does the actual printing
把你示例中的代码与上下文区别开来将有帮助
使用注释将代码与上下文以及输出区别开来将帮助 Clojure 新手开发者在自己的 REPL 中匹配示例的可执行部分。
好
;; You can use destructuring to have keyword arguments. This would be a pretty ;; verbose version of map (in an example a bit more verbose than the first above):(defn keyworded-map [& {function :function sequence :sequence}]
(map function seq));; You call it like this:
(keyworded-map :sequence [1 2 3] :function #(+ % 2))
;;=> (3 4 5);; The declaration can be shortened with “:keys” if your local variables should be
;; named in the same way as your keys in the map:(defn keyworded-map [& {:keys [function sequence]}]
(map function sequence))
对于非常简单的示例，不用加注释也可以。
请遵循此 Scheme 风格指南 中概述的惯例，它遵循 Emacs（以及其他）的缩进和格式化惯例。我们意识到代码风格往往在很大程度上取决于个人偏好，但是在 ClojureDocs 上的示例的统一性很重要。
行的最大宽度应为 80 个字符，以防止在 ClojureDocs 页面上显示时换行，并且请使用空格而非制表符缩进。
考虑在 REPL 输出之后留下一行空白，使你的示例在视觉上更易于浏览。
差
(println "foo") ;; foo ;;=> nil (println "bar") ;; bar ;;=> nil (println "baz") ;; baz ;;=> nil
好
(println "foo") ;; foo ;;=> nil(println “bar”)
;; bar
;;=> nil(println “baz”)
;; baz
;;=> nil
示例源中的 URL 会自动转换为链接。请在适当的地方使用它们以链接到外部资源。