Michael Fogus just published a post about Marginalia, a new documentation system for Clojure based on Jeremy Ashkenas’ Docco for CoffeeScript. It’s work that Fogus started on late last year, and which Zachary Kim (the creator of ClojureDocs) picked up and improved on. The goal for Marginalia is to build a literate programming system, or something close to it, around Clojure.

My first exposure to the concept of literate programming was about ten years ago, when I was still doing a lot of work with Python. Edward K. Ream’s Leo was the tool that I used to experiment with LP, and to be honest, I didn’t get it. The idea of LP, as I thought I understood it then, was that you wanted your documentation and code to be intertwined, and readable: more like literature for humans, and less like a structured formula for computers. But the user interface for Leo required you to build up your system in a highly structured outline form. It was tedious. Writing code with Leo didn’t feel like any sort of programming I’d done before, and trying to write documentation with Leo sure didn’t feel like any sort of writing I’d done before. So after playing with it for awhile, and then getting frustrated with it, I moved on and haven’t thought any more literate programming until this morning.

Marginalia (in its current incarnation) takes a decidedly different, and for me more familiar tack, of embedding documentation comments directly in code. In that sense it’s no different from JavaDoc, or RDoc, or most other software documentation systems today. As you would hope, it picks up directly on the docstrings that you provide for namespaces, functions, etc.

It also parses out more general documentation text that you embed in comments that start with two semicolons.

Note that it supports Markdown-style formatting in both your docstrings as well as these special documentation comments. There’s also support for some fancier stuff, like displaying mathematical formulas written in LaTeX, that uses the MathJAX engine under the hood, but I haven’t gotten around to trying that yet.

I must admit that the primary attraction of Marginalia for me at the moment is that it produces pretty documentation. I’m a sucker for pretty documentation. But I am intrigued by Fogus’ claim that “The very process of using Marginalia will help to crystalize your understanding of [the] problem and its solution(s).” Near the end of his blog post, he proposes a set of guidelines (based on a similar set by Reg Braithwaite) for incorporating Marginalia into your Clojure software development process to achieve that goal.

Now, if you’re really into literate programming, Fogus’ blog post also refers (in a footnote) to Tim Daly’s work on “Clojure in Small Pieces”, a fork of the Clojure source code (re)written in LP style. This strikes me as a very ambitious effort, but one that I plan to keep tabs on as well. It will be interesting to see how studying this re-interpretation of the Clojure code influences one’s understanding of Clojure’s design and implementation.

From the better-late-than-never department, a reminder that the next meeting of the newly-formed Huntsville Functional Programming Group (HuntFunc, for short) will be held Tuesday, January 4, starting at 11:00 a.m. at the 347. That’s tomorrow, for you and me. The plan is for Joe Kutner to give a presentation comparing the concurrency features in various functional programming languages (Clojure, Erlang and Scala). Bret Young will also be presenting a brief introduction to Clojure.

If you’re interested in meeting with fellow software developers to learn more about functional programming languages, how to think about them and use them in your own work, please come join us! We have folks of all experience levels and all are welcome, whether you’re new to FP or have been doing it for years.

So I’m starting to learn Clojure, using Stuart Halloway’s book Programming Clojure as a guide. It’s a steep learning curve for me as I’ve only ever done procedural and object-oriented programming, save for a brief dalliance with Scheme in a programming course I took in graduate school.

I get the basic concepts of functional programming (immutable data, functions without side effects, etc.) but am nowhere near the point where this functional mindset comes naturally to me. I still want to break things down into objects, with methods that carry out actions step-by-step.

One of the the things about Clojure that seems to be tripping me up a lot is the syntax surrounding the ns, use and require special forms. For example, one of the first references to use occurs on p. 19 of Programming Clojure, and it looks like this:

A bit later, on p. 38, he reintroduces use, but this time the example looks like this:

Now, I get that in the first example, he’s saying “only use the str-join function from the clojure.contrib.str-utils library,” while in the second example he’s using everything. What I don’t get is the differing syntax, using a quoted vector in the first example, and a quoted list in the second. It sort-of makes me think that this should work too:

but of course it doesn’t, and I get a mostly useless error message in the REPL. Now, if you’re an experienced Lisp, Scheme or Clojure programmer, you probably understand why this last example is wrong and you really don’t understand how I could possibly think that could be right, but I’m just not there yet. But I’m working on it!

Another thing that has hindered my progress a bit is the way that Clojure’s standard library and its API documentation are organized. Take the clojure.core library for example: it contains several hundred functions, and unless you already know the name of the function you’re looking for, tracking down just the right function for what you need is like looking for a needle in a haystack. For example, a little program I was playing with yesterday dealt with a list of maps, like so:

Now what I wanted was to convert this list of maps into a single map, where the names of the relation types were the keys and the values were the relation types themselves; i.e. a result like this:

After looking through the API documentation for clojure.core I decided there wasn’t any function that would perform this kind of transformation directly (or at least not that I could tell). I also determined (I think) that there’s only one function, hash-map, that will produce a map from its inputs; everything else seems to produce a list/sequence. So anyways, I ended up going with this approach:

and it works, but I’m looking at it and wondering, is this the best way to do this? Is there maybe a more efficient approach than first constructing a list of the type names, then interleaving those with the types to produce yet another list, and finally using hash-map to convert it into a map?

Having said all that, the challenge of learning this new (to me) approach to programming is fun, and I anticipate that it’s going to affect how I think about programs that I write in the languages that I already know well, like Ruby and Java. I’m also excited about finally having what feels like a more “practical” Lisp to play with, one that I can use with existing Java libraries that I work with every day.