Miscellaneous fixes to transplanted style guide
This commit is contained in:
Kevin Yap
parent
112a075d89
commit
d684ea1eed
@ -4,7 +4,7 @@ Hy Style Guide
|
||||
|
||||
“You know, Minister, I disagree with Dumbledore on many counts…but
|
||||
you cannot deny he’s got style…”
|
||||
— Phineas Nigellus Black, Harry Potter & the Order of the Phoenix
|
||||
— Phineas Nigellus Black, *Harry Potter and the Order of the Phoenix*
|
||||
|
||||
The Hy style guide intends to be a set of ground rules for the Hyve
|
||||
(yes, the Hy community prides itself in appending Hy to everything)
|
||||
@ -18,7 +18,7 @@ Prelude
|
||||
The Tao of Hy
|
||||
-------------
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
Ummon asked the head monk, "What sutra are you lecturing on?"
|
||||
"The Nirvana Sutra."
|
||||
@ -36,14 +36,14 @@ The Tao of Hy
|
||||
The following illustrates a brief list of design decisions that went
|
||||
into the making of Hy.
|
||||
|
||||
+ Look like a lisp, DTRT with it (e.g. dashes turn to underscores,
|
||||
earmuffs turn to all-caps.)
|
||||
+ Look like a Lisp; DTRT with it (e.g. dashes turn to underscores, earmuffs
|
||||
turn to all-caps).
|
||||
+ We're still Python. Most of the internals translate 1:1 to Python internals.
|
||||
+ Use unicode everywhere.
|
||||
+ Fix the bad decisions in Python 2 when we can (see true_division)
|
||||
+ Use Unicode everywhere.
|
||||
+ Fix the bad decisions in Python 2 when we can (see ``true_division``).
|
||||
+ When in doubt, defer to Python.
|
||||
+ If you're still unsure, defer to Clojure
|
||||
+ If you're even more unsure, defer to Common Lisp
|
||||
+ If you're still unsure, defer to Clojure.
|
||||
+ If you're even more unsure, defer to Common Lisp.
|
||||
+ Keep in mind we're not Clojure. We're not Common Lisp. We're
|
||||
Homoiconic Python, with extra bits that make sense.
|
||||
|
||||
@ -58,41 +58,41 @@ Layout & Indentation
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; good (and preferred):
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
;; Good (and preferred)
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
|
||||
;; still OK:
|
||||
(defn fib [n]
|
||||
(if (<= n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
|
||||
;; Still okay
|
||||
(defn fib [n]
|
||||
(if (<= n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
|
||||
|
||||
;; still OK:
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
;; Still okay
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
|
||||
;; Stupid as hell
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n ;; Yes, I love randomly hitting the space key
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
;; Hysterically ridiculous
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n ;; yes, I love randomly hitting the space key
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
|
||||
|
||||
+ Parens must *never* be left alone, sad and lonesome on their own
|
||||
+ Parentheses must *never* be left alone, sad and lonesome on their own
|
||||
line.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; good (and preferred):
|
||||
;; Good (and preferred)
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n
|
||||
(+ (fib (- n 1)) (fib (- n 2)))))
|
||||
|
||||
;; Stupid as hell
|
||||
;; Hysterically ridiculous
|
||||
(defn fib [n]
|
||||
(if (<= n 2)
|
||||
n
|
||||
@ -101,29 +101,25 @@ Layout & Indentation
|
||||
) ; GAH, BURN IT WITH FIRE
|
||||
|
||||
|
||||
+ **`let` blocks**
|
||||
|
||||
Align vertically the `let` blocks
|
||||
+ Vertically align ``let`` blocks.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
(let [[foo (bar)]
|
||||
[qux (baz)]]
|
||||
(foo qux))
|
||||
(let [[foo (bar)]
|
||||
[qux (baz)]]
|
||||
(foo qux))
|
||||
|
||||
|
||||
+ **Inline comments**
|
||||
|
||||
Inline comments shall be two spaces from the end of the code, they
|
||||
+ Inline comments shall be two spaces from the end of the code; they
|
||||
must always have a space between the comment character and the start
|
||||
of the comment. Also try not commenting the obvious
|
||||
of the comment. Also, try to not comment the obvious.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; Good
|
||||
(setv ind (dec x)) ; indexing starts from 0
|
||||
|
||||
;; Style compliant but just states the obvious
|
||||
;; Style-compliant but just states the obvious
|
||||
(setv ind (dec x)) ; sets index to x-1
|
||||
|
||||
;; Bad
|
||||
@ -133,12 +129,12 @@ Layout & Indentation
|
||||
Coding Style
|
||||
============
|
||||
|
||||
+ As a convention, try not to use `def` for other than global
|
||||
variables, use `setv` inside functions,loops etc.
|
||||
+ As a convention, try not to use ``def`` for anything other than global
|
||||
variables; use ``setv`` inside functions, loops, etc.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; good (and preferred)
|
||||
;; Good (and preferred)
|
||||
(def *limit* 400000)
|
||||
|
||||
(defn fibs [a b]
|
||||
@ -146,74 +142,61 @@ Coding Style
|
||||
(yield a)
|
||||
(setv (, a b) (, b (+ a b)))))
|
||||
|
||||
;; bad & not preferred
|
||||
;; Bad (and not preferred)
|
||||
(defn fibs [a b]
|
||||
(while true
|
||||
(yield a)
|
||||
(def (, a b) (, b (+ a b)))))
|
||||
|
||||
|
||||
+ Do not use the s-expression syntax where vector syntax is intended.
|
||||
For instance, the fact that:
|
||||
+ Do not use s-expression syntax where vector syntax is intended.
|
||||
For instance, the fact that the former of these two examples works
|
||||
is just because the compiler isn't overly strict. In reality, the
|
||||
correct syntax in places such as this is the latter.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; bad (and evil)
|
||||
;; Bad (and evil)
|
||||
(defn foo (x) (print x))
|
||||
(foo 1)
|
||||
|
||||
|
||||
works is just because the compiler isn't overly strict. In reality,
|
||||
the correct syntax in places such as this is:
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; good (and preferred):
|
||||
;; Good (and preferred)
|
||||
(defn foo [x] (print x))
|
||||
(foo 1)
|
||||
|
||||
|
||||
+ Threading Macro
|
||||
|
||||
Use the threading macro or the threading tail macros when
|
||||
encountering deeply nested s-expressions
|
||||
+ Use the threading macro or the threading tail macros when encountering
|
||||
deeply nested s-expressions. However, be judicious when using them. Do
|
||||
use them when clarity and readability improves; do not construct
|
||||
convoluted, hard to understand expressions.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; preferred
|
||||
(def *names*
|
||||
(with [f (open "names.txt")]
|
||||
(-> (.read f) (.strip) (.replace "\"" "") (.split ",") (sorted))))
|
||||
|
||||
;; not so good
|
||||
;; Preferred
|
||||
(def *names*
|
||||
(with [f (open "names.txt")]
|
||||
(sorted (.spilt "," (.replace "\"" "" (.strip (.read f)))))))
|
||||
(-> (.read f) (.strip) (.replace "\"" "") (.split ",") (sorted))))
|
||||
|
||||
;; Not so good
|
||||
(def *names*
|
||||
(with [f (open "names.txt")]
|
||||
(sorted (.spilt "," (.replace "\"" "" (.strip (.read f)))))))
|
||||
|
||||
However be judicious when using them, do use them when clarity and
|
||||
readability improves. Do not construct convoluted hard to understand
|
||||
expressions
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; This is probably not a good idea
|
||||
;; Probably not a good idea
|
||||
(defn square? [x]
|
||||
(->> 2 (pow (int (sqrt x))) (= x)))
|
||||
|
||||
|
||||
+ Dot Notation
|
||||
|
||||
The clojure style dot notation is preferred over the direct call of
|
||||
the object's method, though both will continue to be supported
|
||||
+ Clojure-style dot notation is preferred over the direct call of
|
||||
the object's method, though both will continue to be supported.
|
||||
|
||||
.. code-block:: clj
|
||||
|
||||
;; good:
|
||||
;; Good
|
||||
(with [fd (open "/etc/passwd")]
|
||||
(print (.readlines fd)))
|
||||
|
||||
;; not so good:
|
||||
;; Not so good
|
||||
(with [fd (open "/etc/passwd")]
|
||||
(print (fd.readlines)))
|
||||
|
||||
@ -221,14 +204,14 @@ expressions
|
||||
Conclusion
|
||||
==========
|
||||
|
||||
“Fashions fade, style is eternal”
|
||||
—Yves Saint Laurent
|
||||
“Fashions fade, style is eternal”
|
||||
—Yves Saint Laurent
|
||||
|
||||
|
||||
This guide is just a set of community guidelines, obviously community
|
||||
guidelines do not make sense without an active
|
||||
community. Contributions are welcome. Join us at #hy in freenode, blog
|
||||
about it, tweet about it, and importantly have fun with Hy
|
||||
This guide is just a set of community guidelines, and obviously, community
|
||||
guidelines do not make sense without an active community. Contributions are
|
||||
welcome. Join us at #hy in freenode, blog about it, tweet about it, and most
|
||||
importantly, have fun with Hy.
|
||||
|
||||
|
||||
Thanks
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user