laid down some initial groundwork

Author: Bozhidar Batsov

README.md

@@ -1,4 +1,175 @@
-clojure-style-guide
-===================
+# The Clojure Style Guide
 
-A community coding style guide for the Clojure programming language
+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. I've
+tried to add the rationale behind the rules (if it's omitted I've
+assumed that is pretty obvious).
+
+I didn't come up with all the rules out of nowhere - they are mostly
+based on my extensive career as a professional software engineer,
+feedback and suggestions from members of the Clojure community and
+various highly regarded Clojure programming resources, such as
+["Clojure Programming"](http://www.clojurebook.com/)
+and ["The Joy of Clojure"](http://joyofclojure.com/).
+
+The guide is still a work in progress - some rules are lacking
+examples, some rules don't have examples that illustrate them clearly
+enough. In due time these issues will be addressed - just keep them in
+mind for now.
+
+You can generate a PDF or an HTML copy of this guide using
+[Transmuter](https://github.com/TechnoGate/transmuter).
+
+## Table of Contents
+
+* [Source Code Layout](#source-code-layout)
+* [Syntax](#syntax)
+* [Naming](#naming)
+* [Comments](#comments)
+* [Annotations](#annotations)
+* [Exceptions](#exceptions)
+* [Collections](#collections)
+* [Strings](#strings)
+* [Regular Expressions](#regular-expressions)
+* [Macros](#macros)
+* [Misc](#misc)
+
+## Source Code Layout
+
+> 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... <br/>
+> -- Jerry Coffin (on indentation)
+
+* Use two **spaces** per indentation level. No hard tabs.
+
+ ```Clojure
+ # good
+ (when something
+ (something-else))
+
+ # bad - four spaces
+ (when something
+ (something-else))
+ ```
+
+* Use Unix-style line endings. (*BSD/Solaris/Linux/OSX users are covered by default,
+ Windows users have to be extra careful.)
+ * If you're using Git you might want to add the following
+ configuration setting to protect your project from Windows line
+ endings creeping in:
+
+ $ git config --global core.autocrlf true
+
+
+* Use empty lines between `def`s.
+
+ ```Clojure
+ (def x ...)
+ 
+ (def y ...)
+ ```
+
+* Keep lines up to 80 characters.
+* Avoid trailing whitespace.
+
+## Comments
+
+> Good code is its own best documentation. As you're about to add a
+> comment, ask yourself, "How can I improve the code so that this
+> comment isn't needed?" Improve the code and then document it to make
+> it even clearer. <br/>
+> -- Steve McConnell
+
+* Write self-documenting code and ignore the rest of this section. Seriously!
+* Comments longer than a word are capitalized and use punctuation. Use [one
+ space](http://en.wikipedia.org/wiki/Sentence_spacing) after periods.
+* Avoid superfluous comments.
+
+ ```Clojure
+ # bad
+ (inc counter) ; increments counter by one
+ ```
+
+* Keep existing comments up-to-date. An outdated is worse than no comment
+at all.
+
+> Good code is like a good joke - it needs no explanation. <br/>
+> -- Russ Olsen
+
+* Avoid writing comments to explain bad code. Refactor the code to
+ make it self-explanatory. (Do or do not - there is no try. --Yoda)
+
+## Annotations
+
+* Annotations should usually be written on the line immediately above
+ the relevant code.
+* The annotation keyword is followed by a colon and a space, then a note
+ describing the problem.
+* If multiple lines are required to describe the problem, subsequent
+ lines should be indented two spaces after the `;;`.
+
+ ```Clojure
+ (defn some-fun
+ []
+ ;; FIXME: This has crashed occasionally since v1.2.3. It may
+ ;; be related to the BarBazUtil upgrade.
+ (baz))
+ ```
+
+* In cases where the problem is so obvious that any documentation would
+ be redundant, annotations may be left at the end of the offending line
+ with no note. This usage should be the exception and not the rule.
+
+ ```Clojure
+ (defn bar
+ []
+ (sleep 100)) ;; OPTIMIZE
+ ```
+
+* Use `TODO` to note missing features or functionality that should be
+ added at a later date.
+* Use `FIXME` to note broken code that needs to be fixed.
+* Use `OPTIMIZE` to note slow or inefficient code that may cause
+ performance problems.
+* Use `HACK` to note code smells where questionable coding practices
+ were used and should be refactored away.
+* Use `REVIEW` to note anything that should be looked at to confirm it
+ is working as intended. For example: `REVIEW: Are we sure this is how the
+ client does X currently?`
+* Use other custom annotation keywords if it feels appropriate, but be
+ sure to document them in your project's `README` or similar.
+
+## Misc
+
+* Avoid functions longer than 10 LOC (lines of code). Ideally, most
+ functions will be shorter than 5 LOC. Empty lines do not contribute
+ to the relevant LOC.
+* Avoid parameter lists longer than three or four parameters.
+* Code in a functional way, avoiding mutation when that makes sense.
+* Avoid more than three levels of block nesting.
+* Be consistent. In an ideal world, be consistent with these guidelines.
+* Use common sense.
+
+# Contributing
+
+Nothing written in this guide is set in stone. It's my desire to work
+together with everyone interested in Clojure coding style, so that we could
+ultimately create a resource that will be beneficial to the entire Clojure
+community.
+
+Feel free to open tickets or send pull requests with improvements. Thanks in
+advance for your help!
+
+# Spread the Word
+
+A community-driven style guide is of little use to a community that
+doesn't know about its existence. Tweet about the guide, share it with
+your friends and colleagues. Every comment, suggestion or opinion we
+get makes the guide just a little bit better. And we want to have the
+best possible guide, don't we?