clojure-style-guide

The Clojure Style Guide Introduction Role models are important. — Officer Alex J. Murphy / RoboCop Tip You can find a beautiful version of this guide with much improved navigation at https://guide.clojure.style. This Clojure style guide recommends best practices so that real-world Clojure programmers can write code that can be maintained by other real-world Clojure programmers. A style guide that reflects real-world usage gets used, and a style guide that holds to an ideal that has been rejected by the people it is supposed to help risks not getting used at all — no matter how good it is. The guide is separated into several sections of related rules. We’ve tried to add the rationale behind the rules (if it’s omitted, we’ve assumed that it’s pretty obvious). We didn’t come up with all the rules out of nowhere; they are mostly based on the experience of the style guide’s editors, feedback and suggestions from numerous members of the Clojure community, and various highly regarded Clojure programming resources, such as "Clojure Programming" and "The Joy of Clojure". Nothing written here is set in stone. This style guide evolves over time as additional conventions are identified and past conventions are rendered obsolete by changes in Clojure itself. Note Clojure’s developers also maintain a list of coding guidelines for libraries.[1] They were one of the sources of inspiration for the document you’re currently reading. You can generate a PDF copy of this guide using AsciiDoctor PDF, and an HTML copy with AsciiDoctor using the following commands: # Generates README.pdf asciidoctor-pdf -a allow-uri-read README.adoc # Generates README.html asciidoctor Tip Install the rouge gem to get nice syntax highlighting in the generated document. gem install rouge Guiding Principles Programs must be written for people to read, and only incidentally for machines to execute. — Harold Abelson Structure and Interpretation of Computer Programs 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 straightforward, 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 Note About Consistency A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines. — Ralph Waldo Emerson 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 Translations of the guide are available in the following languages: Chinese Hungarian Italian (Under progress) Japanese Korean Portuguese (Under progress) Russian Spanish Turkish Note These translations are not maintained by our editor team, so their quality and level of completeness may vary. The translated versions of the guide often lag behind the upstream English version. Source Code Layout & Organization Nearly everybody is convinced that every style but their own is ugly and unreadable. Leave out the "but their own" and they’re probably right…​ — Jerry Coffin (on indentation) Maximum Line Length Where feasible, avoid making lines longer than 80 characters. Why Bother with 80 characters in a World of Modern Widescreen Displays? A lot of people these days feel that a maximum line length of 80 characters is just a remnant of the past and makes little sense today. After all - modern displays can easily fit 200+ characters on a single line. Still, there are some important benefits to be gained