Clojure offers a number of different forms that define types (and generate Java classes). Choosing between
gen-class can be a tripping point for those new to Clojure.
I'd obviously like to make such decisions easier for everyone. I know that many people learn best through visual aids, so I've been working on a flowchart that attempts to encapsulate some of the significant choices that go into deciding between the different type-definition forms. A draft of it is below; let me know if it is helpful to you (or not!), how you think it could be made better, etc. The most recent version of the flowchart, the "source" OmniGraffle file, and many translations of it (feel free to contribute another one!) will always be available here.
"The 'Interop Zone'" demarcates use cases (e.g. needing to define multiple constructors) and forms (
gen-class) that are exclusively the domain of Clojure's JVM interoperability support. Using these forms is fine, but be aware that by doing so, you are stepping outside of Clojure's "native" abstractions; unless you are defining a type for the express purpose of meeting interoperability requirements, one of Clojure's simpler type-definition forms may suit your needs better.
Updated 2011-07-05 18:28 UTC based on initial feedback. Thanks!
Updated 2011-07-07 17:38 UTC — added "The 'Interop Zone'"
Updated 2011-08-23 17:33 UTC — Portuguese translation provided by Paulo Suzart
Final update: The most recent version of the flowchart, the "source" OmniGraffle file, and many translations of it (feel free to contribute another one!) will always be available here.