Programs must be written for people to read, and only incidentally for machines to execute.

It’s common knowledge that code is read much more often than it is written. The guidelines provided here are intended to improve the readability of code and make it consistent across the wide spectrum of Clojure code. They are also meant to reflect real-world usage of Clojure instead of a random ideal. When we had to choose between a very established practice and a subjectively better alternative we’ve opted to recommend the established practice.^[2]

There are some areas in which there is no clear consensus in the Clojure community regarding a particular style (like semantic indentation vs fixed indentation, semantic comments vs uniform comments, etc). In such scenarios all popular styles are acknowledged and it’s up to you to pick one and apply it consistently.

Fortunately Clojure is a Lisp, and Lisps are fundamentally simple. Even though this guide was created a few years after Clojure (the first version was published in early 2013), you could see that most Clojure code in the wild was fairly uniform. We attribute this to both the simplicity we already mentioned and to the fact that since day 1 Clojurists adopted many of the style conventions of other established Lisp dialects (e.g. Common Lisp and Scheme). This made the work on this guide fairly easy and straight-forward, especially compared to the massive exercise in frustration that was the Community Ruby Style Guide.^[3]

Clojure is famously optimized for simplicity and clarity. We’d like to believe that this guide is going to help you optimize for maximum simplicity and clarity.

A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines.

A style guide is about consistency.^[4] Consistency with this style guide is important. Consistency within a project is more important. Consistency within one class or method is the most important.

However, know when to be inconsistent — sometimes style guide recommendations just aren’t applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

In particular: do not break backwards compatibility just to comply with this guide!

Some other good reasons to ignore a particular guideline:

• When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this style guide.

• To be consistent with surrounding code that also breaks it (maybe for historic reasons) — although this is also an opportunity to clean up someone else’s mess (in true XP style).

• Because the code in question predates the introduction of the guideline and there is no other reason to be modifying that code.

• When the code needs to remain compatible with older versions of Clojure that don’t support the feature recommended by the style guide.

Translations of the guide are available in the following languages:

• Chinese

• Italian (Under progress)

• Japanese

• Korean

• Portuguese (Under progress)

• Russian

• Spanish

• Turkish

Where feasible, avoid making lines longer than 80 characters.

Use spaces for indentation. No hard tabs.

Use 2 spaces to indent the bodies of forms that have body parameters. This covers all def forms, special forms and macros that introduce local bindings (e.g. loop, let, when-let) and many macros like when, cond, as->, cond->, case, with-*, etc.

Vertically align function (macro) arguments spanning multiple lines.

The reasoning behind this guideline is pretty simple - the arguments are easier to process by the human brain if they stand out and stick together.

Use a single space indentation for function (macro) arguments when there are no arguments on the same line as the function name.

This may appear like some weird special rule to people without Lisp background, but the reasoning behind it is quite simple. Function calls are nothing but regular list literals and normally those are aligned in the same way as other collection type literals when spanning multiple lines:

Admittedly, list literals are not very common in Clojure, that’s why it’s understandable that for many people lists are nothing but an invocation syntax.

As a side benefit, function arguments are still aligned in this scenario as well. They just happen to accidentally be aligned with the function name as well.

Vertically align let (and let-like) bindings.

Align vertically map keys.

Use Unix-style line endings.^[5]

End each file with a newline.

If any text precedes an opening bracket((, { and [) or follows a closing bracket(), } and ]), separate that text from that bracket with a space. Conversely, leave no space after an opening bracket and before following text, or after preceding text and before a closing bracket.

Syntactic sugar causes semicolon cancer.

Don’t use commas between the elements of sequential collection literals.

Consider enhancing the readability of map literals via judicious use of commas and line breaks.

Place all trailing parentheses on a single line instead of distinct lines.

Use a single empty line between top-level forms.

An exception to the rule is the grouping of related defs together.

Do not place blank lines in the middle of a function or macro definition. An exception can be made to indicate grouping of pairwise constructs as found in e.g. let and cond, in case those don’t fit on the same line.

Occasionally, it might seem like a good idea to add a blank line here and there in a longer function definition, but if you get to this point you should also consider whether this long function isn’t doing too much and could potentially be broken down.

Avoid trailing whitespace.

Use one file per namespace and one namespace per file.

Avoid single-segment namespaces.

Namespaces exist to disambiguate names. Using a single segment namespace puts you in direct conflict with everyone else using single segment namespaces, thus making it more likely you will conflict with another code base.

In practice this means that libraries should never use single-segment namespace to avoid namespace conflicts with other libraries. Within your own private app of course, you can do whatever you like.

There are other reasons why might want to avoid single-segment namespaces, so you should think long and hard before making any use of them.

Avoid the use of overly long namespaces (i.e., more than 5 segments).

Start every namespace with a comprehensive ns form, comprised of refers, requires, and imports, conventionally in that order.

When there are multiple dependencies, you may want give each one its own line. This facilitates sorting, readability, and cleaner diffs for dependency changes.

In the ns form prefer :require :as over :require :refer over :require :refer :all. Prefer :require over :use; the latter form should be considered deprecated for new code.

In the ns form, sort your requirements and imports. This facilitates readability and avoids duplication, especially when the list of required / imported namespaces is very long.

Many core Clojure namespaces have idiomatic aliases that you’re encouraged to use within your projects - e.g. the most common way to require clojure.string is: [clojure.string :as str].

As noted in the next section, it’s generally considered idiomatic to use an alias that is the last segment of the namespace, if that makes it unique, or else the two segments, typically dropping redundant parts like clj or core.

Amongst Clojure’s core and Contrib namespaces, the following namespaces have idiomatic aliases following that pattern:

Then there are some core and Contrib namespaces that have shorter idiomatic aliases:

And amongst commonly used community libraries, there are also many that have widely-used, idiomatic aliases for several namespaces:

Above we covered a handful of popular namespaces and their idiomatic aliases. You might have noticed that those are a bit inconsistent:

• clojure.string becomes str

• clojure.pprint becomes pp

• clojure.walk becomes walk

• clojure.spec.alpha becomes s

It’s clear that the one thing they have in common is that they aim to be concise, but still carry some meaning (aliasing clojure.walk to w would be concise, but won’t carry much meaning).

But what to do about all the other namespaces out there that don’t have idiomatic aliases? Well, you better be consistent in your approach to deriving aliases for them, otherwise the people working on a shared Clojure codebase are going to experience a great deal of confusion. Here are a few rules that you should follow.^[6]

1. Make the alias the same as the namespace name with the leading parts removed.

1. Keep enough trailing parts to make each alias unique.

1. Eliminate redundant words such as "core" and "clj" in aliases.

Across a project, it’s good to be consistent with namespace aliases; e.g., don’t require clojure.string as str in one namespace but string in another. 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 consistently within your projects.

When naming namespaces favor the following two schemas:

• project.module

• organization.project.module

When you’re following the project.module naming scheme and your project has a single (implementation) namespace it’s common to name it project.core. Avoid the project.core name in all other cases, as more informative names are always a better idea.

Use lisp-case in composite namespace segments (e.g. bruce.project-euler).

Use lisp-case for function and variable names.

Use CapitalCase for protocols, records, structs, and types. (Keep acronyms like HTTP, RFC, XML uppercase.)

The names of predicate methods (methods that return a boolean value) should end in a question mark (e.g., even?).

The names of functions/macros that are not safe in STM transactions should end with an exclamation mark (e.g. reset!).

Use -> instead of to in the names of conversion functions.

Use earmuffs for things intended for rebinding (ie. are dynamic).

Don’t use a special notation for constants; everything is assumed a constant unless specified otherwise.

Use _ for destructuring targets and formal argument names whose value will be ignored by the code at hand.

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.

Follow clojure.core's example for idiomatic names like pred and coll.

• in functions:

  • f, g, h - function input

  • n - integer input usually a size

  • index, i - integer index

  • x, y - numbers

  • xs - sequence

  • m - map

  • k, ks - key, keys

  • v, vs - value, values (as in a key/value pair)

  • s - string input

  • re - regular expression

  • sym - symbol

  • coll - a collection

  • pred - a predicate closure

  • & more - variadic input

  • xf - xform, a transducer

  • ns - namespace^[7]

• in macros:

  • expr - an expression

  • body - a macro body

  • binding - a macro binding vector

• in methods (when specified in defprotocol, deftype, defrecord, reify, etc):

  • this - for the first argument, indicating a reference to the object - or alternatively, a consistent name which describes the object

Optionally omit the new line between the function name and argument vector for defn when there is no docstring.

Place the dispatch-val of a multimethod on the same line as the function name.

Optionally omit the new line between the argument vector and a short function body.

Indent each arity form of a function definition vertically aligned with its parameters.

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.

Avoid functions longer than 10 LOC (lines of code). Ideally, most functions will be shorter than 5 LOC.

Avoid parameter lists with more than three or four positional parameters.

Prefer function pre and post conditions to checks inside a function’s body.

Avoid the use of namespace-manipulating functions like require and refer. They are entirely unnecessary outside of a REPL environment.

Avoid forward references. They are occasionally necessary, but such occasions are rare in practice.

Use declare to enable forward references when forward references are necessary.

Prefer higher-order functions like map to loop/recur.

Don’t define vars inside functions.

Don’t shadow clojure.core names with local bindings.

Use alter-var-root instead of def to change the value of a var.

Use seq as a terminating condition to test whether a sequence is empty (this technique is sometimes called nil punning).

Prefer vec over into when you need to convert a sequence into a vector.

Use the boolean function if you need to convert something to an actual boolean value (true or false).

You’ll rarely need an actual boolean value in Clojure, but it’s useful to know how to obtain one when you do.

Use when instead of if with just the truthy branch, as in (if condition (something…​)) or (if …​ (do …​)).

Use if-let instead of let + if.

Use when-let instead of let + when.

Use if-not instead of (if (not …​) …​).

Use when-not instead of (when (not …​) …​).

Use when-not instead of (if-not …​ (do …​)).

Use not= instead of (not (= …​)).

Prefer printf over (print (format …​)).

When doing comparisons, leverage the fact that Clojure’s functions <, >, etc. accept a variable number of arguments.

Prefer % over %1 in function literals with only one parameter.

Prefer %1 over % in function literals with more than one parameter.

Don’t wrap functions in anonymous functions when you don’t need to.

Don’t use function literals if the function body will consist of more than one form.

Prefer anonymous functions over complement, comp and partial, as this results in simpler code most of the time.^[8]

complement

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

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

comp

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

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

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

;; good
(def xf
  (comp
    (filter odd?)
    (map inc)
    (take 5)))

partial

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

;; okish
(map (partial + 5) (range 1 10))

Prefer the use of the threading macros -> (thread-first) and ->> (thread-last) to heavy form nesting.

Parentheses are not required when using the threading macros for functions having no argument specified, so use them only when necessary.

The arguments to the threading macros -> (thread-first) and ->> (thread-last) should line up.

Use :else as the catch-all test expression in cond.

Prefer condp instead of cond when the predicate & expression don’t change.

Prefer case instead of cond or condp when test expressions are compile-time constants.

Use short forms in cond and related. If not possible give visual hints for the pairwise grouping with comments or empty lines.

Use a set as a predicate when appropriate.

Use (inc x) & (dec x) instead of (+ x 1) and (- x 1).

Use (pos? x), (neg? x) & (zero? x) instead of (> x 0), (< x 0) & (= x 0).

Use list* instead of a series of nested cons invocations.

Use the sugared Java interop forms.

Use the compact metadata notation for metadata that contains only slots whose keys are keywords and whose value is boolean true.

Denote private parts of your code.

To access a private var (e.g. for testing), use the @#'some.ns/var form.

Be careful regarding what exactly you attach metadata to.

Avoid the use of lists for generic data storage (unless a list is exactly what you need).

Prefer the use of keywords for hash keys.

Prefer the use of the literal collection syntax where applicable. However, when defining sets, only use literal syntax when the values are compile-time constants.

Avoid accessing collection members by index whenever possible.

Prefer the use of keywords as functions for retrieving values from maps, where applicable.

Leverage the fact that most collections are functions of their elements.

Leverage the fact that keywords can be used as functions of a collection.

Avoid the use of transient collections, except for performance-critical portions of the code.

Avoid the use of Java collections.

Avoid the use of Java arrays, except for interop scenarios and performance-critical code dealing heavily with primitive types.

Don’t use the interop syntax to construct type and record instances. deftype and defrecord automatically create constructor functions. Use those instead of the interop syntax, as they make it clear that you’re dealing with a deftype or a defrecord. See this article for more details.

Note that deftype doesn’t define the map->Type constructor. It’s available only for records.

Add custom type/record constructors when needed (e.g. to validate properties on record creation). See this article for more details.

Feel free to adopt whatever naming convention or structure you’d like for such custom constructors.

Don’t override the auto-generated type/record constructor functions. People expect them to have a certain behaviour and changing this behaviour violates the principle of least surprise. See this article for more details.

io! Macro

Avoid ref-set

(def r (ref 0))

;; good
(dosync (alter r + 5))

;; bad
(dosync (ref-set r 5))

Small Transactions

Avoid Short Long Transactions With Same Ref

Agents Send

Agents Send Off

No Updates Within Transactions

Prefer swap! over reset!

(def a (atom 0))

;; good
(swap! a + 5)

;; not as good
(reset! a 5)

Prefer math functions from clojure.math over (Java) interop or rolling your own.

The JDK package java.lang.Math provides access to many useful math functions. Prior to version 1.11, Clojure relied on using these via interop, but this had issues with discoverability, primitive performance, higher order application, and portability. The new clojure.math namespace provides wrapper functions for the methods available in java.lang.Math for long and double overloads with fast primitive invocation.

Prefer string manipulation functions from clojure.string over Java interop or rolling your own.

Reuse existing exception types. Idiomatic Clojure code — when it does throw an exception — throws an exception of a standard type (e.g. java.lang.IllegalArgumentException, java.lang.UnsupportedOperationException, java.lang.IllegalStateException, java.io.IOException).

Favor with-open over finally.

Don’t write a macro if a function will do.

Create an example of a macro usage first and the macro afterwards.

Break complicated macros into smaller functions whenever possible.

A macro should usually just provide syntactic sugar and the core of the macro should be a plain function. Doing so will improve composability.

Prefer syntax-quoted forms over building lists manually.

The most common way to document when a public API was added to a library is via the :added metadata.

The most common way to document when a public API was changed in a library is via the :changed metadata. This metadata makes sense only for vars and you should be using it sparingly, as changing the behavior of a public API is generally a bad idea.

Still, if you decide to do it, it’s best to make that clear to the API users.

The most common way to mark deprecated public APIs is via the :deprecated metadata. Normally you’d use as the value the version in which something was deprecated in case of versioned software (e.g. a library) or simply true in the case of unversioned software (e.g. some web application).

Often you’d combine :deprecated with :superseded-by, as there would be some newer API that supersedes whatever got deprecated.

Typically for vars you’ll use a non-qualified name if the replacement lives in the same namespace, and a fully-qualified name otherwise.

From time to time you might want to point out some related vars/namespaces that the users of your library might be interested in. The most common way to do so would be via the :see-also metadata, which takes a vector of related items. When talking about vars - items in the same namespace don’t need to fully qualified.

Documentation tools like Codox like cljdoc recognize :no-doc metadata. When a var or a namespace has :no-doc metadata, it indicates to these tools that it should be excluded from generated API docs.

To exclude an entire namespace from API docs:

To exclude vars within a documented namespace:

Unlike other Lisp dialects, Clojure doesn’t have a standard metadata format to specify the indentation of macros. CIDER proposed a tool-agnostic indentation specification based on metadata in 2015.^[9] Here’s a simple example:

This instructs the indentation engine that this is a macro with one ordinary parameter and a body after it.

Unfortunately, as of 2020 there’s still no widespread adoption of :style/indent and many editors and IDEs would just hardcode the indentation rules for common macros.

Endeavor to make your code as self-explanatory as possible. If you fail to achieve this follow the rest of the guidelines in this section.

Write heading comments with at least four semicolons. Those typically serve to outline/separate major section of code, or to describe important ideas. Often you’d have a section comment followed by a bunch of top-level comments.

Write top-level comments with three semicolons.

Write comments on a particular fragment of code before that fragment and aligned with it, using two semicolons.

Write margin comments with one semicolon.

Avoid using those in situations that would result in hanging closing parentheses.

Always have at least one space between the semicolon and the text that follows it.

Comments longer than a word begin with a capital letter and use punctuation. Separate sentences with one space.

Obviously punctuation is not the most important thing about a comment, but a bit of extra effort results in better experience for the readers of our comments.

Avoid superfluous comments.

Keep existing comments up-to-date. An outdated comment is worse than no comment at all.

Prefer the use of the #_ reader macro over a regular comment when you need to comment out a particular form.

Good code is like a good joke - it needs no explanation.

Avoid writing comments to explain bad code. Refactor the code to make it self-explanatory. ("Do, or do not. There is no try." --Yoda)

Annotate Above

;; good
(defn some-fun
  []
  ;; FIXME: Replace baz with the newer bar.
  (baz))

;; bad
;; FIXME: Replace baz with the newer bar.
(defn some-fun
  []
  (baz))

Annotate Keywords

;; good
(defn some-fun
  []
  ;; FIXME: Replace baz with the newer bar.
  (baz))

;; bad - no colon after annotation
(defn some-fun
  []
  ;; FIXME Replace baz with the newer bar.
  (baz))

;; bad - no space after colon
(defn some-fun
  []
  ;; FIXME:Replace baz with the newer bar.
  (baz))

Indent Annotations

;; good
(defn some-fun
  []
  ;; FIXME: This has crashed occasionally since v1.2.3. It may
  ;;        be related to the BarBazUtil upgrade. (xz 13-1-31)
  (baz))

;; bad
(defn some-fun
  []
  ;; FIXME: This has crashed occasionally since v1.2.3. It may
  ;; be related to the BarBazUtil upgrade. (xz 13-1-31)
  (baz))

Sign and Date Annotations

(defn some-fun
  []
  ;; FIXME: This has crashed occasionally since v1.2.3. It may
  ;;        be related to the BarBazUtil upgrade. (xz 13-1-31)
  (baz))

Rare Margin (EOL) Annotations

(defn bar
  []
  (sleep 100)) ; OPTIMIZE

TODO

FIXME

OPTIMIZE

HACK

REVIEW

Document Custom Annotations

If a form supports docstrings directly prefer them over using :doc metadata:

Let the first line in the docstring be a complete, capitalized sentence which concisely describes the var in question. This makes it easy for tooling (Clojure editors and IDEs) to display a short a summary of the docstring at various places.

Important tools such as cljdoc support Markdown in docstrings so leverage it for nicely formatted documentation.

Document all positional arguments, and wrap them them with backticks (`) so that editors and IDEs can identify them and potentially provide extra functionality for them.

Wrap any var references in the docstring with ` so that tooling can identify them. Wrap them with [[..]] if you want to link to them.

Docstrings should be composed of well-formed English sentences. Every sentence should start with a capitalized word, be grammatically coherent, and end with appropriate punctuation. Sentences should be separated with a single space.

Indent multi-line docstrings by two spaces.

Neither start nor end your docstrings with any whitespace.

When adding a docstring — especially to a function using the above form — take care to correctly place the docstring after the function name, not after the argument vector. The latter is not invalid syntax and won’t cause an error, but includes the string as a form in the function body without attaching it to the var as documentation.

Store your tests in a separate directory, typically test/yourproject/ (as opposed to src/yourproject/). Your build tool is responsible for making them available in the contexts where they are necessary; most templates will do this for you automatically.

Name your ns yourproject.something-test, a file which usually lives in test/yourproject/something_test.clj (or .cljc, cljs).

When using clojure.test, define your tests with deftest and name them something-test.

If you are publishing libraries to be used by others, make sure to follow the Central Repository guidelines for choosing your groupId and artifactId. This helps to prevent name conflicts and facilitates the widest possible use. A good example is Component - its coordinates are com.stuartsierra/component.

Another approach that’s popular in the wild is to use a project (or organization) name as the groupId instead of domain name. Examples of such naming would be:

• cider/cider-nrepl

• nrepl/nrepl

• nrepl/drawbridge

• clj-commons/fs

Avoid unnecessary dependencies. For example, a three-line utility function copied into a project is usually better than a dependency that drags in hundreds of vars you do not plan to use.

Deliver core functionality and integration points in separate artifacts. That way, consumers can consume your library without being constrained by your unrelated tooling preferences. For example, Component provides core functionality, and reloaded provides leiningen integration.

Code in a functional way, using mutation only when it makes sense.

Be consistent. In an ideal world, be consistent with these guidelines.

Use common sense.

There are some lint tools created by the Clojure community that might aid you in your endeavor to write idiomatic Clojure code.

• kibit is a static code analyzer for Clojure which uses core.logic to search for patterns of code for which there might exist a more idiomatic function or macro.

• clj-kondo is a linter that detects a wide number of discouraged patterns and suggests improvements, based on this style guide.

While most Clojure editors and IDEs can format the code, according to the layout guidelines outlined here, it’s always handy to have some command-line code formatting tools. There are a couple of options for Clojure that do a great job when it comes to formatting the code as suggested in this guide:

• cljfmt

• cljstyle

• zprint (the documentation for configuring it to use the community formatting rules is here)

It’s easy, just follow the contribution guidelines below:

• Fork bbatsov/clojure-style-guide on GitHub

• Make your feature addition or bug fix in a feature branch.

• Include a good description of your changes

• Push your feature branch to GitHub

• Send a Pull Request