The example sections on each var page are there to provide simple, isolated examples of var usage. In a nutshell, the examples you add to Clojuredocs should be easy to understand, and to help you with that we’ve outlined a few guidelines below.
Examples should be short, unique, self-contained snippets of code that illustrate var usage in the simplest possible way.
If the target var is not part of the core ns (or otherwise not used by default) please include the use / require statement.
Bad:
(sh “ls” “-aul”)
;; {:exit 0,
;; :out “total 64
;; drwxr-xr-x 11 zkim staff 374 Jul 5 13:21 .”
;; …
Good:
(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 .”
…
Each example should be either broad, or deep, not both. For example, the following example for not= shows the broad range of inputs allowed.
(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
Where this example for future has depth.
;; 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
Also, please mention any gotchas you feel are associated with your example (specifically) or the var (in general).
Comments should be used to describe the following code block or blocks and/or point out bits of information that may not be obvious to new Clojure devs.
Bad:
(with-precision 10 (/ 1M 3)) ;;=> 0.3333333333Muser=> (.floatValue 0.3333333333M)
;;=> 0.33333334
Good:
;; 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
;; should be for a general comment about a block of code, ; should be used to add a comment to the end of a line of code.
Bad:
; This function will print 'hello world' to the console (defn hello-world [] (println "hello world")) ;; Does the actual printing
Good:
;; This function will print 'hello world' to the console (defn hello-world [] (println "hello world")) ; Does the actual printing
Differentiating code from context in your example will help
Using comments to differentiate code from context and output will help new Clojure devs match up the executable parts of your example in their REPLs.
Good:
;; 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))
Feel free to omit comments for very simple examples.
Please follow the conventions outlined in this Scheme style guide, which follows Emacs’ (among others) indentation and formatting conventions. We realize that code style can often be largely dictated by personal preference, however, uniformity across examples on ClojureDocs is important.
Lines should have a maximum width of 80 characters to prevent wrapping when displayed on ClojureDocs pages, and please indent with spaces, not tabs.
Consider leaving one line of whitespace after output from the repl to make your examples easier to visually scan.
Bad:
(println "foo") ;; foo ;;=> nil (println "bar") ;; bar ;;=> nil (println "baz") ;; baz ;;=> nil
Good:
(println "foo") ;; foo ;;=> nil(println “bar”)
;; bar
;;=> nil(println “baz”)
;; baz
;;=> nil
Urls in examples source are automatically converted to links. Feel free to use them where appropriate to link to external resources.