A sly introduction to documented functions
I can't remember the exact page on which the authors of The Joy of Clojure introduce what looks like function comments but it's obvious what they are and I learnt it obliquely. Here's the quote where I realised I understood something new without explicitly being told:
~~~ (defn keys-apply [f ks m] "Takes a function, a set of keys, and a map and applies the function to the map on the given keys. A new map of the result of the function applied to the keyed entries is returned." (let [only (select-keys m ks)] (zipmap (keys only) (map f (vals only))))) ~~~
This has nothing to do with my astuteness and everything to do with good teaching.
These types of comment are called docstrings. But this term seems tacit because, although it's mentioned a lot on clojure.org, I couldn't find much in the way of a definition. But it seems the term is fairly common if you're a LISPer.