[bbatsov#109] Add advisory for sorting arities

Author: arrdem

README.md

@@ -259,6 +259,40 @@ when there are no arguments on the same line as the function name.
  (foo x 1))
  ([x y]
  (+ x y)))
+```
+
+* <a name="multiple-arity-order"></a> Sort the arities of a function
+ from fewest to most arguments. The common case of multi-arity
+ functions is that some K arguments fully specifies the function's
+ behavior, and that arities N < K partially apply the K arity, and
+ arities N > K provide a fold of the K arity over varargs.
+ <sup>[[link](#multiple-arity-order)]</sup>
+
+ ```Clojure
+ ;; good - it's easy to scan for the nth arity
+ (defn foo
+ "I have two arities."
+ ([x]
+ (foo x 1))
+ ([x y]
+ (+ x y)))
+
+ ;; okay - the other arities are applications of the two-arity 
+ (defn foo
+ "I have two arities."
+ ([x y]
+ (+ x y))
+ ([x]
+ (foo x 1))
+ ([x y z & more]
+ (reduce foo (foo x (foo y z)) more)))
+ 
+;; bad - unordered for no apparent reason
+(defn foo
+ ([x] 1)
+ ([x y z] (foo x (foo y z)))
+ ([x y] (+ x y))
+ ([w x y z & more] (reduce foo (foo w (foo x (foo y z))) more)))
  ```
 
 * <a name="align-docstring-lines"></a>