The Clojure Style Guide: Community Coding Conventions for Real-World Clojure

What the Clojure Style Guide Covers and Who It Is For

The Clojure Style Guide is a community-maintained reference document that collects coding conventions for the Clojure programming language. It is aimed at programmers who write Clojure for real projects and who need to read and maintain code written by others. The README states its purpose plainly: to enable code that can be maintained by real-world Clojure programmers, grounded in what the community actually does rather than abstract ideals.

The guide covers naming conventions, formatting and indentation, idiomatic use of Clojure's standard constructs, and library design guidelines. Each rule includes a rationale where the reason is not obvious. The first version was published in early 2013. Since Clojure is a Lisp with a small surface area, most Clojure code in the wild was already fairly uniform before the guide existed, which the README attributes to the language's simplicity and to Clojure's early adoption of conventions from Common Lisp and Scheme.

The guide is maintained by Bozhidar Batsov and community contributors. It is written in AsciiDoc format and published as a rendered website at https://guide.clojure.style.

How the Repository Is Organised and How to Navigate It

The repository is minimal. The primary file is README.adoc, which contains the entire guide in AsciiDoc format. The repository also contains CONTRIBUTING.md for contribution instructions, cs-excludelines.txt and cs-ignorewords.txt for spell-checking configuration, and a .github/ directory for workflow definitions.

The guide itself is divided into multiple sections of related rules. The table of contents (generated from AsciiDoc section anchors) is the primary navigation tool in the rendered HTML version at guide.clojure.style. The README states that the website version has much-improved navigation compared to reading the raw AsciiDoc on GitHub.

For day-to-day reference, the website is the practical choice: it renders the full guide with syntax-highlighted code examples and section anchors that can be bookmarked. Cloning the repository is only necessary if you want to generate a local copy in PDF or HTML format, or if you want to contribute a change.

Generating a Local PDF or HTML Copy

The guide can be rendered locally using AsciiDoctor. To produce a PDF:

asciidoctor-pdf -a allow-uri-read README.adoc

This writes README.pdf to the current directory. To produce an HTML file, run AsciiDoctor without the PDF plugin:

asciidoctor

For syntax highlighting in the generated document, install the `rouge` gem first:

gem install rouge

These commands are documented in the README's introduction. They assume Ruby and the AsciiDoctor toolchain are already installed. The guide does not document AsciiDoctor installation steps; those come from the AsciiDoctor project itself.

Consistency Principles and Areas Where the Guide Does Not Prescribe a Single Answer

The guide explicitly addresses the question of when to deviate from its recommendations. It identifies four legitimate reasons to ignore a guideline: when following it would reduce readability for someone familiar with the style, when the surrounding code consistently breaks the rule for historical reasons, when the code predates the rule and there is no other reason to change it, and when the code must remain compatible with older Clojure versions that lack a recommended feature.

This approach is drawn from Python's PEP-8, which the README acknowledges as an inspiration. The guide frames consistency at three levels: project consistency matters more than style-guide consistency, and method-level consistency matters most of all.

On some questions, the Clojure community has no clear consensus. The README names semantic versus fixed indentation and semantic versus uniform comments as two such areas. For these cases, the guide documents all popular styles and leaves the choice to the team, as long as the chosen approach is applied consistently. This is a practical position for a community guide: prescribing one approach for a disputed question would make the guide less useful to teams that have already settled on a different convention.

What the Guide Does Not Cover

The Clojure Style Guide does not cover ClojureScript. ClojureScript has its own idioms around JavaScript interop, namespace conventions, and compilation output that are not addressed in this document.

The guide does not enforce anything automatically. It is a reference document, not a linter or a formatter. Teams that want automated enforcement need a separate tool, and the related searches show that cljfmt is the commonly paired option. The README does not mention cljfmt or any other formatter.

The translations listed in the guide (Chinese, Hungarian, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Turkish) are maintained by separate contributors in separate repositories. The README includes a note that these translations are not maintained by the original project. A translation may be months or years behind the current version of the guide; teams working in those languages should verify the translation's currency before relying on it.

The guide does not document build tooling, project layout, or dependency management conventions. Those topics are outside its stated scope.

Clojure Style Guide vs. Official Clojure Coding Guidelines

The Clojure core team maintains a separate set of coding guidelines at clojure.org/community/contrib_howto. The README identifies this as one of the inspirations for the community guide. The difference in scope is stated clearly: the official guidelines are written for Clojure itself and for all Clojure Contrib libraries. They are not general-purpose application style guidance.

For teams writing application code or libraries outside the Contrib ecosystem, the community style guide at guide.clojure.style is the broader and more directly applicable reference. It draws on the official guidelines but extends them with conventions for everyday application development. The two documents are complementary: the official guidelines are authoritative for contributions to Clojure core and Contrib; the community guide covers the wider range of decisions a Clojure developer faces in production application work.

The README also notes that the Clojure community's adoption of Common Lisp and Scheme conventions from day one meant there was less friction in creating this guide than Batsov encountered with the Community Ruby Style Guide, which the README describes as a much more complex exercise.

Maintenance History and Licensing

The last push to the repository was on 2026-09-18. The guide has been actively updated since its first release in early 2013, a period of over thirteen years. The AsciiDoc source lives in the master branch. The repository has no GitHub releases; updates are made directly to the README.adoc file.

The repository's license is not stated in the README, and no license file appears in the top-level file listing. Teams that need to redistribute or adapt the content should check the repository directly before doing so.

Contributions are accepted through the CONTRIBUTING.md workflow. The guide evolves as Clojure adds new features that make older conventions obsolete, or as community consensus shifts. The README explicitly states that nothing in the guide is set in stone.

Editorial conclusion

The Clojure Style Guide is worth reading for any developer who writes Clojure professionally or contributes to shared codebases. Teams that adopt it should pick one of the acknowledged alternatives where the guide explicitly does not prescribe a single answer, such as indentation style, and apply it consistently. The guide does not auto-enforce anything; pair it with a tool like cljfmt for automated checking of formatting rules.

Frequently asked questions

Official sources

1. bbatsov/clojure-style-guide on GitHub
2. Issues
3. Project website
4. README