Skip to content

Commit 946c08c

Browse files
bbatsovbbatsov
committed
Pull the Naming section earlier in the guide
1 parent 5fb6475 commit 946c08c

File tree

1 file changed

+162
-162
lines changed

1 file changed

+162
-162
lines changed

‎README.adoc

Lines changed: 162 additions & 162 deletions
Original file line numberDiff line numberDiff line change
@@ -730,6 +730,168 @@ Across a project, it's good to be consistent with namespace aliases; e.g., don't
730730
If you follow the previous two guidelines you're basically covered, but if you opt for custom namespace aliasing scheme it's still important to apply it
731731
consistently within your projects.
732732

733+
== Naming
734+
735+
[quote, Phil Karlton]
736+
____
737+
The only real difficulties in programming are cache invalidation and
738+
naming things.
739+
____
740+
741+
=== Namespace Naming Schemas [[naming-ns-naming-schemas]]
742+
743+
When naming namespaces favor the following two schemas:
744+
745+
* `project.module`
746+
* `organization.project.module`
747+
748+
=== Composite Word Namespace Segments [[naming-namespace-composite-segments]]
749+
750+
Use `lisp-case` in composite namespace segments (e.g. `bruce.project-euler`).
751+
752+
=== Functions and Variables [[naming-functions-and-variables]]
753+
754+
Use `lisp-case` for function and variable names.
755+
756+
NOTE: Many non-Lisp programming communities refer to `lisp-case` as
757+
`kebab-case`, but we all know that Lisp has existed way before kebab
758+
was invented.
759+
760+
[source,clojure]
761+
----
762+
;; good
763+
(def some-var ...)
764+
(defn some-fun ...)
765+
766+
;; bad
767+
(def someVar ...)
768+
(defn somefun ...)
769+
(def some_fun ...)
770+
----
771+
772+
=== Protocols, Records, Structs And Types [[naming-protocols-records-structs-and-types]]
773+
774+
Use `CapitalCase` for protocols, records, structs, and types. (Keep
775+
acronyms like HTTP, RFC, XML uppercase.)
776+
777+
NOTE: `CapitalCase` is also known as `UpperCamelCase, `CapitalWords`
778+
and `PascalCase`.
779+
780+
=== Predicate Methods [[naming-predicates]]
781+
782+
The names of predicate methods (methods that return a boolean value)
783+
should end in a question mark
784+
(e.g., `even?`).
785+
786+
[source,clojure]
787+
----
788+
;; good
789+
(defn palindrome? ...)
790+
791+
;; bad
792+
(defn palindrome-p ...) ; Common Lisp style
793+
(defn is-palindrome ...) ; Java style
794+
----
795+
796+
=== Unsafe Functions [[naming-unsafe-functions]]
797+
798+
The names of functions/macros that are not safe in STM transactions
799+
should end with an exclamation mark (e.g. `reset!`).
800+
801+
=== Conversion Functions [[naming-conversion-functions]]
802+
803+
Use `+->+` instead of `to` in the names of conversion functions.
804+
805+
[source,clojure]
806+
----
807+
;; good
808+
(defn f->c ...)
809+
810+
;; not so good
811+
(defn f-to-c ...)
812+
----
813+
814+
=== Dynamic Vars [[naming-dynamic-vars]]
815+
816+
Use `*earmuffs*` for things intended for rebinding (ie. are dynamic).
817+
818+
[source,clojure]
819+
----
820+
;; good
821+
(def ^:dynamic *a* 10)
822+
823+
;; bad
824+
(def ^:dynamic a 10)
825+
----
826+
827+
=== Constants [[naming-constants]]
828+
829+
Don't use a special notation for constants; everything is assumed a constant
830+
unless specified otherwise.
831+
832+
=== Unused Bindings [[naming-unused-bindings]]
833+
834+
Use `+_+` for destructuring targets and formal argument names whose
835+
value will be ignored by the code at hand.
836+
837+
[source,clojure]
838+
----
839+
;; good
840+
(let [[a b _ c] [1 2 3 4]]
841+
(println a b c))
842+
843+
(dotimes [_ 3]
844+
(println "Hello!"))
845+
846+
;; bad
847+
(let [[a b c d] [1 2 3 4]]
848+
(println a b d))
849+
850+
(dotimes [i 3]
851+
(println "Hello!"))
852+
----
853+
854+
However, when it can help the understanding of your code, it can be useful to explicitly name unused arguments or maps you're destructuring from. In this case, prepend the name with an underscore to explicitly signal that the variable is supposed to be unused.
855+
856+
[source,clojure]
857+
----
858+
;; good
859+
(defn myfun1 [context _]
860+
(assoc context :foo "bar"))
861+
862+
(defn myfun2 [context {:keys [id]}]
863+
(assoc context :user-id id))
864+
865+
;; better
866+
(defn myfun1 [context _user]
867+
(assoc context :foo "bar"))
868+
869+
(defn myfun2 [context {:keys [id] :as _user}]
870+
(assoc context :user-id id))
871+
----
872+
873+
=== Idiomatic Names [[idiomatic-names]]
874+
875+
Follow ``clojure.core``'s example for idiomatic names like `pred` and `coll`.
876+
877+
* in functions:
878+
** `f`, `g`, `h` - function input
879+
** `n` - integer input usually a size
880+
** `index`, `i` - integer index
881+
** `x`, `y` - numbers
882+
** `xs` - sequence
883+
** `m` - map
884+
** `s` - string input
885+
** `re` - regular expression
886+
** `coll` - a collection
887+
** `pred` - a predicate closure
888+
** `& more` - variadic input
889+
** `xf` - xform, a transducer
890+
* in macros:
891+
** `expr` - an expression
892+
** `body` - a macro body
893+
** `binding` - a macro binding vector
894+
733895
== Functions
734896

735897
=== Optional New Line After Function Name [[optional-new-line-after-fn-name]]
@@ -1544,168 +1706,6 @@ Be careful regarding what exactly you attach metadata to.
15441706
(meta #'a) ;=> nil
15451707
----
15461708

1547-
== Naming
1548-
1549-
[quote, Phil Karlton]
1550-
____
1551-
The only real difficulties in programming are cache invalidation and
1552-
naming things.
1553-
____
1554-
1555-
=== Namespace Naming Schemas [[naming-ns-naming-schemas]]
1556-
1557-
When naming namespaces favor the following two schemas:
1558-
1559-
* `project.module`
1560-
* `organization.project.module`
1561-
1562-
=== Composite Word Namespace Segments [[naming-namespace-composite-segments]]
1563-
1564-
Use `lisp-case` in composite namespace segments (e.g. `bruce.project-euler`).
1565-
1566-
=== Functions and Variables [[naming-functions-and-variables]]
1567-
1568-
Use `lisp-case` for function and variable names.
1569-
1570-
NOTE: Many non-Lisp programming communities refer to `lisp-case` as
1571-
`kebab-case`, but we all know that Lisp has existed way before kebab
1572-
was invented.
1573-
1574-
[source,clojure]
1575-
----
1576-
;; good
1577-
(def some-var ...)
1578-
(defn some-fun ...)
1579-
1580-
;; bad
1581-
(def someVar ...)
1582-
(defn somefun ...)
1583-
(def some_fun ...)
1584-
----
1585-
1586-
=== Protocols, Records, Structs And Types [[naming-protocols-records-structs-and-types]]
1587-
1588-
Use `CapitalCase` for protocols, records, structs, and types. (Keep
1589-
acronyms like HTTP, RFC, XML uppercase.)
1590-
1591-
NOTE: `CapitalCase` is also known as `UpperCamelCase, `CapitalWords`
1592-
and `PascalCase`.
1593-
1594-
=== Predicate Methods [[naming-predicates]]
1595-
1596-
The names of predicate methods (methods that return a boolean value)
1597-
should end in a question mark
1598-
(e.g., `even?`).
1599-
1600-
[source,clojure]
1601-
----
1602-
;; good
1603-
(defn palindrome? ...)
1604-
1605-
;; bad
1606-
(defn palindrome-p ...) ; Common Lisp style
1607-
(defn is-palindrome ...) ; Java style
1608-
----
1609-
1610-
=== Unsafe Functions [[naming-unsafe-functions]]
1611-
1612-
The names of functions/macros that are not safe in STM transactions
1613-
should end with an exclamation mark (e.g. `reset!`).
1614-
1615-
=== Conversion Functions [[naming-conversion-functions]]
1616-
1617-
Use `+->+` instead of `to` in the names of conversion functions.
1618-
1619-
[source,clojure]
1620-
----
1621-
;; good
1622-
(defn f->c ...)
1623-
1624-
;; not so good
1625-
(defn f-to-c ...)
1626-
----
1627-
1628-
=== Dynamic Vars [[naming-dynamic-vars]]
1629-
1630-
Use `*earmuffs*` for things intended for rebinding (ie. are dynamic).
1631-
1632-
[source,clojure]
1633-
----
1634-
;; good
1635-
(def ^:dynamic *a* 10)
1636-
1637-
;; bad
1638-
(def ^:dynamic a 10)
1639-
----
1640-
1641-
=== Constants [[naming-constants]]
1642-
1643-
Don't use a special notation for constants; everything is assumed a constant
1644-
unless specified otherwise.
1645-
1646-
=== Unused Bindings [[naming-unused-bindings]]
1647-
1648-
Use `+_+` for destructuring targets and formal argument names whose
1649-
value will be ignored by the code at hand.
1650-
1651-
[source,clojure]
1652-
----
1653-
;; good
1654-
(let [[a b _ c] [1 2 3 4]]
1655-
(println a b c))
1656-
1657-
(dotimes [_ 3]
1658-
(println "Hello!"))
1659-
1660-
;; bad
1661-
(let [[a b c d] [1 2 3 4]]
1662-
(println a b d))
1663-
1664-
(dotimes [i 3]
1665-
(println "Hello!"))
1666-
----
1667-
1668-
However, when it can help the understanding of your code, it can be useful to explicitly name unused arguments or maps you're destructuring from. In this case, prepend the name with an underscore to explicitly signal that the variable is supposed to be unused.
1669-
1670-
[source,clojure]
1671-
----
1672-
;; good
1673-
(defn myfun1 [context _]
1674-
(assoc context :foo "bar"))
1675-
1676-
(defn myfun2 [context {:keys [id]}]
1677-
(assoc context :user-id id))
1678-
1679-
;; better
1680-
(defn myfun1 [context _user]
1681-
(assoc context :foo "bar"))
1682-
1683-
(defn myfun2 [context {:keys [id] :as _user}]
1684-
(assoc context :user-id id))
1685-
----
1686-
1687-
=== Idiomatic Names [[idiomatic-names]]
1688-
1689-
Follow ``clojure.core``'s example for idiomatic names like `pred` and `coll`.
1690-
1691-
* in functions:
1692-
** `f`, `g`, `h` - function input
1693-
** `n` - integer input usually a size
1694-
** `index`, `i` - integer index
1695-
** `x`, `y` - numbers
1696-
** `xs` - sequence
1697-
** `m` - map
1698-
** `s` - string input
1699-
** `re` - regular expression
1700-
** `coll` - a collection
1701-
** `pred` - a predicate closure
1702-
** `& more` - variadic input
1703-
** `xf` - xform, a transducer
1704-
* in macros:
1705-
** `expr` - an expression
1706-
** `body` - a macro body
1707-
** `binding` - a macro binding vector
1708-
17091709
== Data Structures
17101710

17111711
[quote, Alan J. Perlis]

0 commit comments

Comments
 (0)