Literate Programming
Literate Programming: I’ve always been fascinated by it (as I am with anything Knuth’s done). Here’s the Wikipedia entry, which has at least one example:
Over the years, I’ve done things kind of like it (extracting docs from code and vice-versa) and I could have already written some useless stuff here along the lines of "what LP means to me." But as of yesterday, I’ve got something way better. I’ve got a tiny working demonstration and the thoughts it provoked fresh in my head.
Here’s the demo:
RubyLit - This README is a program! ("A literate programming system in 35 lines of Ruby")
I’m so happy I finally tried this "real" LP experiment. After sleeping on it (but before the excitement has worn off, ha ha), I’d like to write my thoughts.
Fun
So I’ll admit that I’m predisposed to document anyway, but writing this Literate Program felt way more fun (and natural) than writing comments or separate documentation!
Better than comments
Being able to write in paragraph form without having to worry about keeping my indents aligned or being super succinct and all the other fussy details of, you know, code comments, made it a relative breeze to write my thoughts.
It looks different and it feels different.
It was amazing to see my program become a series of little snippets, as if I were merely demonstrating the concept I was describing. Honestly, it makes each little piece of the program seem like a little jewel. I love that.
Better than separate documentation
I didn’t have to come up with convoluted ways to name pieces of code or otherwise identify what I was talking about. The paragraphs obviously described the code in which they were intermixed. So that’s one huge documentation challenge solved right there.
The other huge one is that with LP, I have zero worry the code and documentation will get out of sync because they’re the same dang file.
Best of both worlds and beyond
The final icing on the cake is being able to "tell the story" in any order I wanted.
Presenting the program like documentation makes a really interesting exercise in understanding the program! (I think it’s pretty eye-opening.)
I also can’t help feeling like this puts extra emphasis on software craftsmanship when you see your snippets of code presented in this way, surrounded by prose, like examples from a book.
Downsides, caveats
Big one: Lack of tool support. This toy example is super fun, but not "production ready". (It could be though, right?). I’ve seen a little bit of the existing LP tool landscape and I didn’t like the looks of it.
I have no idea how this scales. I’ve heard rumors that it can get out of hand. But, come on, show me something that can’t get out of hand.
And can you imagine the team that would be able to do this together? It’d be like getting a dozen people together to write a novel. I suspect you’d need one main author and some contributors to pull this off. (Maybe two authors at most? Novelists seem to be able to do that now and then.)
Also note: I wrote the program first, then came back and made it literate. That felt extremely natural, but it would be interesting to:
-
Reverse the process (write the doc part first)
-
Do both at once (good luck!)
Finally, the hard question remains: will I actually use this beyond the demonstration itself? Will I use it in a "real" program? We’ll see!
Back to programming.