The Clojure Style Guide

Clojure 风格指南

榜样很重要。
-- 《机械战警》 Alex J. Murphy 警官

这份 Clojure 旨在为 Clojure 程序员编写简洁易懂，易于维护的高质量 Clojure 代码提供一份最佳实践。无论多么好的风格或指南，但是过于理想化的结果导致大家拒绝使用或者可能根本没人用，毫无意义。

本指南分为几个小节，每一小节由几条相关的规则构成。我尽力在每条规则后面说明理由（如果省略了说明，那是因为其理由显而易见）。

这些规则不是我凭空想象出来的 --- 它们中的绝大部分来自我多年以来作为职业软件工程师的经验，来自 Clojure 社区成员的反馈和建议，以及许多备受推崇的 Clojure 编程资源，例如 "Clojure Programming" 和 "The Joy of Clojure"。

这份指南还处于不断完善中，可能有一些部分是缺失的，可能有一些是不完善的，可能有一些规则缺少例子，可能有一些规例没有用例子阐述的足够清晰。要记住的是，随着时间的推移这些问题都会被解决。

请注意，Clojure 开发者社区同样维护了一份 coding standards for libraries 列表。

组织

所有风格都又丑又难读，自己的除外。几乎人人都这样想。把 “自己的除外” 拿掉，
他们或许是对的...
-- Jerry Coffin（论缩排）

    ;; good
    (foo (bar baz) quux)

    ;; bad
    (foo(bar baz)quux)
    (foo ( bar baz ) quux)

 

语法糖会导致分号癌。
-- Alan Perlis

这个规则的一个例外是，将相关的 def 放在一起。

;; good
(def min-rows 10)
(def max-rows 20)
(def min-cols 15)
(def max-cols 30)

语法

;; good
(when-not pred
    (foo)
    (bar))

;; bad
(when (not pred)
    (foo)
    (bar))

;; good
(when-not pred
    (foo)
    (bar))

;; bad
(if-not pred
    (do
    (foo)
    (bar)))

;; good
(not= foo bar)

;; bad
(not (= foo bar))

;; good
(printf "Hello, %s!\n" name)

;; ok
(println (format "Hello, %s!" name))

;; good
(< 5 x 10)

;; bad
(and (> x 5) (< x 10))

;; good
#(Math/round %)

;; bad
#(Math/round %1)

;; good
#(Math/pow %1 %2)

;; bad
#(Math/pow % %2)

;; good
(filter even? (range 1 10))

;; bad
(filter #(even? %) (range 1 10))

;; good
(fn [x]
    (println x)
    (* x 2))

;; bad (you need an explicit do form)
#(do (println %)
        (* % 2))

;; good
(filter (complement some-pred?) coll)

;; bad
(filter #(not (some-pred? %)) coll)

如果反向谓词作为一个独立函数存在时（例如，`event?` 和 `odd?`），
这条规则可以忽略。

;; Assuming `(:require [clojure.string :as str])`...

;; good
(map #(str/capitalize (str/trim %)) ["top " " test "])

;; better
(map (comp str/capitalize str/trim) ["top " " test "])

;; good
(map #(+ 5 %) (range 1 10))

;; (arguably) better
(map (partial + 5) (range 1 10))

;; good
(-> [1 2 3]
    reverse
    (conj 4)
    prn)

;; not as good
(prn (conj (reverse [1 2 3])
            4))

;; good
(->> (range 1 10)
        (filter even?)
        (map (partial * 2)))

;; not as good
(map (partial * 2)
        (filter even? (range 1 10)))

;; good
(cond
    (< n 0) "negative"
    (> n 0) "positive"
    :else "zero"))

;; bad
(cond
    (< n 0) "negative"
    (> n 0) "positive"
    true "zero"))

;; good
(cond
    (= x 10) :ten
    (= x 20) :twenty
    (= x 30) :thirty
    :else :dunno)

;; much better
(condp = x
    10 :ten
    20 :twenty
    30 :thirty
    :dunno)

;; good
(cond
    (= x 10) :ten
    (= x 20) :twenty
    (= x 30) :forty
    :else :dunno)

;; better
(condp = x
    10 :ten
    20 :twenty
    30 :forty
    :dunno)

;; best
(case x
    10 :ten
    20 :twenty
    30 :forty
    :dunno)

;; good
(cond
    (test1) (action1)
    (test2) (action2)
    :else   (default-action))

;; ok-ish
(cond
    ;; test case 1
    (test1)
    (long-function-name-which-requires-a-new-line
    (complicated-sub-form
        (-> 'which-spans multiple-lines)))

    ;; test case 2
    (test2)
    (another-very-long-function-name
    (yet-another-sub-form
        (-> 'which-spans multiple-lines)))

    :else
    (the-fall-through-default-case
    (which-also-spans 'multiple
                        'lines)))

;; good
(remove #{1} [0 1 2 3 4 5])

;; bad
(remove #(= % 1) [0 1 2 3 4 5])

;; good
(count (filter #{\a \e \i \o \u} "mary had a little lamb"))

;; bad
(count (filter #(or (= % \a)
                    (= % \e)
                    (= % \i)
                    (= % \o)
                    (= % \u))
                "mary had a little lamb"))

;; good
(list* 1 2 3 [4 5])

;; bad
(cons 1 (cons 2 (cons 3 [4 5])))

;;; object creation
;; good
(java.util.ArrayList. 100)

;; bad
(new java.util.ArrayList 100)

;;; static method invocation
;; good
(Math/pow 2 10)

;; bad
(. Math pow 2 10)

;;; instance method invocation
;; good
(.substring "hello" 1 3)

;; bad
(. "hello" substring 1 3)

;;; static field access
;; good
Integer/MAX_VALUE

;; bad
(. Integer MAX_VALUE)

;;; instance field access
;; good
(.someField some-object)

;; bad
(. some-object someField)

;; good
(def ^:private a 5)

;; bad
(def ^{:private true} a 5)

;; good
(defn- private-fun [] ...)

(def ^:private private-var ...)

;; bad
(defn private-fun [] ...) ; not private at all

(defn ^:private private-fun [] ...) ; overly verbose

(def private-var ...) ; not private at all

;; we attach the metadata to the var referenced by `a`
(def ^:private a {})
(meta a) ;=> nil
(meta #'a) ;=> {:private true}

;; we attach the metadata to the empty hash-map value
(def a ^:private {})
(meta a) ;=> {:private true}
(meta #'a) ;=> nil

命名

程序设计的真正难题是替事物命名以及缓存失效。

-- Phil Karlton

;; good
(def some-var ...)
(defn some-fun ...)

;; bad
(def someVar ...)
(defn somefun ...)
(def some_fun ...)

;; good
(defn palindrome? ...)

;; bad
(defn palindrome-p ...) ; Common Lisp style
(defn is-palindrome ...) ; Java style

;; good
(defn f->c ...)

;; not so good
(defn f-to-c ...)

;; good
(def ^:dynamic *a* 10)

;; bad
(def ^:dynamic a 10)

;; good
(let [[a b _ c] [1 2 3 4]]
    (println a b c))

(dotimes [_ 3]
    (println "Hello!"))

;; bad
(let [[a b c d] [1 2 3 4]]
    (println a b d))

(dotimes [i 3]
    (println "Hello!"))

集合

一百个函数去操作一个数据结构要优于十个函数去操作十个数据结构。
-- Alan J. Perlis

;; good
{:name "Bruce" :age 30}

;; bad
{"name" "Bruce" "age" 30}

    ;; good
    [1 2 3]
    #{1 2 3}
    (hash-set (func1) (func2)) ; values determined at runtime

    ;; bad
    (vector 1 2 3)
    (hash-set 1 2 3)
    #{(func1) (func2)} ; will throw runtime exception if (func1) = (func2)

可变性

Refs (引用)

Agents (代理)

Atoms (原子)

字符串

异常

宏

注释

良好的代码自身就是最佳的文档。当你要添加一个注释时， 扪心自问，“如何改善代码让它不需要注释？” 改善代码，再写相应文档使之更清楚。
-- Steve McConnell

 

好的代码就像是好的笑话 —— 它不需要解释。
-- Russ Olsen

注解

经验

工具

下面是一些 Clojure 社区创建的工具，为你写出地道的 Clojure 助一臂之力。

测试

贡献

这份指南中的任何规则都不是一成不变的。 我渴望和任何一位对 Clojure 风格指南的伙伴一起工作， 最终创造一份对整个 Clojure 社区都大有裨益的资源。

欢迎发起讨论或提交一个带有改进性质的更新请求。在此提前感谢你的帮助！

你也可以通过 gittip 对此项目提供财务方面的支持。

Support via Gittip

授权

Creative Commons License 本指南基于 Creative Commons Attribution 3.0 Unported License 授权许可。

口耳相传

一份社区驱动的风格指南，如果没多少人知道， 对一个社区来说就没有多少用处。微博转发这份指南， 分享给你的朋友或同事。我们得到的每个评价、建议或意见都可以让这份指南变得更好一点。 而我们想要拥有最好的指南，不是吗？

共勉之，
Bozhidar

原文地址

https://github.com/geekerzp/clojure-style-guide/blob/master/README-zhCN.md

2019-02-13

上一篇: 成长和晋升
下一篇: 写一个Lein的command/plugin/task

留言