Open-source project
bbatsov/clojure-style-guide avatar
bbatsov/clojure-style-guide

bbatsov/clojure-style-guide: a community style guide for Clojure, and how to use it

A community coding style guide for the Clojure programming language

4,097 stars282 forksUnknownLicense varies

At a glance

What is it?
The Clojure Style Guide is a community-maintained document of formatting and naming conventions, published from a single README.adoc. It is a reference, not a linter, and its value depends on whether your team treats it as a baseline.
Who is it for?
Adopt it if your team wants a written, community-sourced baseline for Clojure formatting and naming, and if you are willing to accept that it is prose rather than tooling. Skip it if you want an enforced formatter: the guide has no executable component, and the repository contains no linter config.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
GitHub does not report a main language for this repository.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • bbatsov/clojure-style-guide4,097 ★ · -3
Star history
Repository2026-09-232026-11-15
bbatsov/clojure-style-guide4.1k4.1k

-3 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What the Clojure Style Guide actually is

It is a document, not a program. The repository is essentially one AsciiDoc file, README.adoc, plus a CONTRIBUTING.md and two small text files used by a spell or line checker. The README states the goal plainly: it recommends practices so that real-world Clojure programmers can write code that can be maintained by other real-world Clojure programmers. That framing matters. The guide is written for teams reading each other's code, not for a compiler or a CI job.

The audience is anyone writing Clojure in a shared codebase. The introduction says the rules are based on the experience of the guide's editors, feedback from the Clojure community, and books such as Clojure Programming and The Joy of Clojure. It also notes that Clojure's own developers maintain a separate list of coding guidelines for libraries, and that those were one of the sources of inspiration here.

The guide is explicitly not set in stone. The README says it evolves as conventions are identified and older ones become obsolete. That is a reasonable stance for a language whose ecosystem is small enough that most code in the wild already looks similar, a point the README makes when it attributes that uniformity to Lisp's simplicity and to early adoption of conventions from Common Lisp and Scheme.

How the guide is structured and where its rules come from

The README.adoc is organised into sections of related rules, with a table of contents generated by Asciidoctor. The introduction says the editors tried to include the rationale behind each rule, and where a rationale is omitted they assumed it was obvious. That is a useful signal when you read a rule and disagree with it: if no reason is given, you are being asked to accept convention on authority.

The stated tie-breaking policy is conservative. When the editors had to choose between a very established practice and a subjectively better alternative, they say they opted to recommend the established practice. They add a footnote that they might occasionally suggest considering alternatives. This is the single most important design decision in the document, because it explains why some rules look dated. The guide optimises for agreement with existing code, not for the cleanest possible style.

Where the community has no consensus, the guide does not pick a winner. It names semantic versus fixed indentation and semantic versus uniform comments as examples, acknowledges all popular styles, and leaves the choice to the reader on the condition of consistency. That is honest, but it also means the guide cannot settle those arguments for you.

Building the HTML and PDF versions locally

There is nothing to install in the sense of a package. The guide is published at guide.clojure.style, and the README explains how to generate your own copies with Asciidoctor. The commands below are quoted from the README's GitHub-only section.

bash
# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc

# Generates README.html
asciidoctor README.adoc

The first command produces README.pdf, and the second produces README.html. The README also suggests installing the rouge gem for syntax highlighting in the generated document.

bash
gem install rouge

After that, rendering the HTML gives you a local copy you can read offline or hand to a new team member. If you only want to read the guide, the hosted version is enough and you can skip the toolchain entirely. The commands above are the only build steps the README documents; there is no make target, no package manifest, and no release artifact to download.

Consistency beats compliance, and the guide says so

The section titled A Note About Consistency borrows its framing from PEP 8 and ranks the obligations: consistency with the guide is important, consistency within a project is more important, and consistency within one class or method is most important. It then lists reasons to ignore a guideline, including cases where applying it makes code less readable, where the surrounding code already breaks it, where the code predates the guideline, and where the code must stay compatible with older Clojure versions that lack the recommended feature.

One line in that section is worth quoting in full because it is the sharpest constraint in the document: do not break backwards compatibility just to comply with this guide. That is an unusual thing for a style guide to say, and it tells you the authors expect their rules to lose against working code.

This is also where the guide is weakest as a decision-making tool. If a rule can be waived for readability, for history, or for compatibility, then two teams reading the same paragraph can reach opposite conclusions and both be following the guide. The document does not provide a mechanism to resolve that, because it is not designed to.

What you do not get: enforcement, tooling, or a stable release

The repository has no releases, and the default branch is master. There is no versioned artifact, so the guide you read today is the master branch README.adoc. If you cite a rule in a code review, cite the section rather than a version number, because there is no version number to cite.

The guide also does not lint anything. Nothing in the repository enforces its rules, and the README does not claim otherwise. If your team wants formatting checked automatically, you need a separate formatter and a separate configuration decision; the guide will tell you what the community considers idiomatic, but it will not fail a build. Treating it as if it were a linter is the most common way to be disappointed by it.

A second limitation is scope. The README notes that the Ruby style guide, which inspired this one's structure, is much longer, mostly because Ruby is more complex. Clojure's simplicity means fewer rules are needed, but it also means the guide covers less ground than a newcomer might expect from a document with this reputation.

Alternatives: a formatter instead of a document

The practical alternative is a code formatter. Cljfmt is the name that comes up in searches around this project, and the difference in approach is fundamental: a formatter rewrites your source to a canonical layout and can run in CI, so the rule is enforced by the tool rather than by a reviewer's memory. The style guide does the opposite. It describes conventions in prose, leaves judgement calls to the reader, and explicitly allows deviation.

The two are not mutually exclusive, and the guide's own posture suggests they should not be treated as rivals. A formatter handles indentation and whitespace mechanically; the guide covers naming, structure and idiom, which a formatter will not touch. If you have to pick one to start with, pick the formatter, because a rule that runs on every commit is worth more than a rule that lives in a document nobody opens. Add the guide when your team starts arguing about things a formatter cannot decide.

Licence, maintenance and the cost of following the guide

The repository metadata does not include a licence, and the README does not state one. If you plan to redistribute the guide, embed it in a product, or translate it, that is the first thing to resolve with the maintainers, because the repository does not answer it. Do not assume a default from the project's age or popularity.

The last push to the repository was on 2026-09-18, so the document is being touched. Maintenance here means edits to a prose file, not releases or dependency upgrades, so the upgrade cost is close to zero: there is nothing to install and nothing to break. The cost that does exist is social. Adopting the guide means someone has to decide which sections your team will follow, and the README's own consistency section gives you permission to follow some and not others. That decision is the work, and the document will not make it for you.

Editorial conclusion

Adopt it if your team wants a written, community-sourced baseline for Clojure formatting and naming, and if you are willing to accept that it is prose rather than tooling. Skip it if you want an enforced formatter: the guide has no executable component, and the repository contains no linter config. Before adopting, read the Consistency section, check whether your team's existing code conflicts with a rule you care about, and decide which sections you will actually enforce. The repository has no release tags, so the master branch README.adoc is the version you get.

Frequently asked questions

Is the Clojure Style Guide a linter or a formatter?

Neither. It is a document of recommended conventions, and the repository contains no tooling that enforces them. If you want automatic formatting you need a separate formatter alongside the guide.

How do I generate an HTML or PDF copy of the Clojure Style Guide?

The README gives two Asciidoctor commands: asciidoctor-pdf -a allow-uri-read README.adoc for the PDF and asciidoctor for the HTML. It also suggests installing the rouge gem for syntax highlighting.

Can I ignore a rule in the Clojure Style Guide?

Yes. The consistency section lists reasons to deviate, including reduced readability, consistency with surrounding code, code that predates the rule, and compatibility with older Clojure versions. It also states that you should not break backwards compatibility just to comply.

Does the Clojure Style Guide have versioned releases?

The repository has no published GitHub releases, and the default branch is master. The README.adoc on master is the current version of the guide.

What licence is the Clojure Style Guide under?

The repository metadata does not include a licence and the README does not state one, so the repository does not answer this. Anyone planning to redistribute or translate it should confirm the terms with the maintainers first.

Official sources

  1. bbatsov/clojure-style-guide on GitHub
  2. Issues
  3. Project website
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/bbatsov-clojure-style-guide.svg)](https://hysenlabs.com/projects/bbatsov-clojure-style-guide)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/bbatsov-clojure-style-guide.svg)](https://hysenlabs.com/projects/bbatsov-clojure-style-guide)

Was this useful?