Getting Clojure

Docstrings

One of the challenges of programming is that code has two audiences, one electronic and the other human. On one hand, code is the medium that we use to order the computer around, and we have to do that ordering with explicit, sometimes painful, precision. But code is also literature. It needs to communicate its intent and workings to the humans who maintain and enhance it.

The traditional way you help the people understand code is via comments. A comment is always as close as the semicolon key. Thus, if we wanted to add a bit of explanation to our average function we might do something like this:

;; Return the average of the two parameters.
(defn average [a b]
  (/ (+ a b) 2.0))

As every programmer knows, the beauty of comments ...