Examples Guidelines Draft

ClojureDocs Example Submission Guidelines

Overview

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.

General Guidelines

Examples should be short, unique, self-contained snippets of code that illustrate var usage in the simplest possible way.

• Try to imagine clear conceptual boundaries of your example before submitting it.
• Assume the reader has a background in software development, with little (but some) Clojure experience.
• Short, sweet, and complete is the name of the game.

If the target var is not part of the core ns (or otherwise not used by default) please include the use / require statement.

Bad: user=> (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]])

user=> (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.

user=> (not= 1 1)
false

user=> (not= 1 2)
true

user=> (not= true true)
false

user=> (not= true false)
true

user=> (not= true true true true)
false

user=> (not= true true false true)
true

Whereas this example for future has depth.

;; A future is calculated in another thread
user=> (def f (future (Thread/sleep 10000) 100))
#'user/f

;; When you dereference it you will block until the result is available.
user=> @f
100

;; Dereferencing again will return the already calculated value immediately.
user=> @f
100

Also, please mention any gotchas you feel are associated with your example (specifically) or the var (in general).

Comments

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: user=> (with-precision 10 (/ 1M 3)) 0.3333333333M

user=> (.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

user=> (with-precision 10 (/ 1M 3))
0.3333333333M

user=> (.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

Lines to be executed should start with user=>, not user>, or >. This is to help new Clojure devs match up your code blocks to the REPL, and will help with automatic verification and reference analysis.

Definitions (def, defn, defmacro, etc) and use / import / require statements can optionally leave out the user=> and #'user/whatever output.

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 can call it like this:
user=> (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))

Comments are not required for very simple examples.

Indentation / Formatting

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, which will make your examples easier to scan visually.

Good: user=> (println "foo") foo nil

user=> (println "bar")
bar
nil

user=> (println "baz")
baz
nil

Bad: user=> (println "foo") foo nil user=> (println "bar") bar nil user=> (println "baz") baz nil

Linking

Urls in examples source are automatically converted to links. Feel free to use them where appropriate to link to external resources.