koans - a pattern for learning languages

As you all know, I’m a big fan of education. One of the best ways that I know to pick up a new language or library is to use one of the really awesome ‘koans’ tutorials that are modeled after the first: Ruby Koans, by EdgeCase.

So what are Koans? Well, there’s been a long tradition in hacker culture to make references to eastern religions; we’ve got Perl Monks, the Tao of Programming, for instance. Back in 2003, esr wrote the UNIX koans of Master Foo, which told the story of various students becoming enlightened. Ruby Koans (and others) continue to enlighten students to this day.

I still haven’t answered, so what is a koan? Well, here’s what Wikipedia says:

A kōan (pronounced /ˈkoʊ.ɑːn/) is a fundamental part of the history and lore of Zen Buddhism. It consists of a story, dialogue, question, or statement, the meaning of which cannot be understood by rational thinking but may be accessible through intuition. One widely known kōan is “Two hands clap and there is a sound; what is the sound of one hand?”

So of course, it’s completely obvious to you that koans are a set of unit tests that ask you questions about the nature of the uni…err, programming.

Check it out. If you want to learn some Ruby, just do this:

$ git clone https://github.com/edgecase/ruby_koans.git
$ cd ruby_koans
$ rake

You’ll get this:

AboutAsserts#test_assert_truth has damaged your karma.

The Master says:
  You have not yet reached enlightenment.

The answers you seek...
  <false> is not true.

Please meditate on the following code:
  ./about_asserts.rb:10:in `test_assert_truth'
  path_to_enlightenment.rb:38:in `each_with_index'
  path_to_enlightenment.rb:38

mountains are merely mountains
your path thus far [X_________________________________________________] 0/274

Get it? If you check out the koans/about_asserts.rb file, line 10, you’ll see this:

  # We shall contemplate truth by testing reality, via asserts.
  def test_assert_truth
    assert false                # This should be true
  end

There are a bunch of these tests (274, at the time of this writing), and they’ll walk you through a bunch of things you’ll need to know if you want to program with Ruby.

This has sort of taken off as a meme, a GitHub search for ‘koans’ shows 92 repositories, most of which are variations on this idea for many different libraries and toolkits.

Not to rest on their laurels, edgecase has a variation of koans up too, ruby_koans_online. Yep. It’s a little sinatra App, that gives you a webpage that shows the koans and allows you to fill things in:

You can then hit a ‘meditate’ button and it’ll change them over from green to red. Fun! It’s still very much a work in progress, it seems: You can see the start of an error there about an ‘insecure operation.’ But otherwise, it’s mostly functional.