pelle/clauth — pull request #6 by rplevy-draker (2012-08-17 22:49:30+00:00)
Title: Clojure conventions idioms and best practices

Hi Pelle,

Apologies for seemingly large size of this pull request. It is actually quite a focused on a few minor, but I would consider important changes, which I list below. These changes improve the adherence to best practices that are widely accepted in throughout the Clojure developer community.

I would also like to add that I have some additional, and more substantial ideas on how to improve clauth, but these changes that do not affect functionality seem to me to be prerequisite to making it easier to contribute these other changes, so I am delaying that until after we deal with these changes.

Changes in this pull request:

1. Formatting of parentheses: in Clojure and the Lisp communities it is derrived from it is a solid convention that closing parentheses never go on a separate line (like C brackets).
2. Expressions like "( a b c)" should instead be "(a b c)" both when being used as code and as data. I fixed these whitespace anomalies as well as other non-syntactic whitespace that occurred in the files in random places.
3. 80-character limit: lines longer than 80 characters have been reformatted in reasonable ways.
4. Indentation: I fixed the irregularities of indentation and apply a more standard Clojure/Lisp indentation style. The one unfortunate effect of this is that it makes the diff difficult to read.
5. There is a debate over "use" vs. "require" (and many now consider "use" semi-deprecated by the 1.4 require :refer feature), but there is general consensus that a naked "use" referring all vars into the namespace makes code very difficult to understand, and I have personally found this to be the case in almost every place I have encountered it. To me it seems there are still many instances in which referring vars by symbol name into a namespace makes sense. For example in tests, I would tend to refer the test framework in wholesale, and when only a var named by a very obvious symbol is needed (such as is frequently the case in clauth.demo for example) I would refer in just that one var. In these cases I believe the the explicit refer adds a lot of clarity to the code, just as do require :as aliases which I consider the best way to clarify the source of a var as long it does not clutter or get in the way.