Developing a Clojure Edge

Testing and Workflow

0. Use Leiningen for managing dependencies and building

lein new edge

1. Use a REPL

2. Save your experiments as tests

3. Autorun tests

https://github.com/marick/Midje

4. Use git

5. refere to http://clojuredocs.org/clojure_core

6. Use clojars, http://www.clojure-toolbox.com/

Interactive Development

Clojure built in test framework

(is (= 1 1))

Midje

(fact “one is one”

1 => 1)

Save your repl experiments as tests

Tests are great for making sure stuff works. But tests and documentation are often the last thing on a programmer's mind. Even if you have a testing regime in place, implementing useful tests is actually quite an art that requires experience and thought.

Examples are a subset of tests.

Actually examples are a really important subset of tests because they inevitably are concerned with the API you are exposing, not the internals of your implementation. This is a very high payoff place to have tests. So much so you can think of examples as 'essential tests'. Not only does this mean they are important to provide, but it also means if you are providing examples then you are generating high value tests without additional deep thinking or experience required.

Examples make excellent documentation.

Examples are a really great way to learn anything new. This is especially true in programming. Including examples in documentation of code communicates clearly what the code does and how it should be used. They also get the reader thinking about scenarios where they could use this stuff in ways that reading a description often does not convey.

One thing people fear about documenting examples is 'what if they get out of date?'. Indeed this is a concern. But if our examples are really just important tests, then this concern disappears. Of course our examples will be kept up to date because we are using them as tests. Important tests that we need to pass. If we can achieve both testing and documentation from one activity the payoff to cost is much more appealing.

Another concern is if the examples are too far removed from the code then they wont be created as part of the coding process. We want our development cycle to be closely knit with producing examples so these don't become a separate activate which could fall by the wayside. Performing documentation as a separate task rarely works well unless you have someone dedicated on the case. Documentation generated from source code improves the chance of survival.