Giles Bowkett wrote a post which, at the surface, seems to be a harsh criticism of the way that Pythonistas and, in particular, Django developers view Ruby and Rails but is actually much more general — he simply wanted to point out that the entire notion of calling language/framework features “magic” is silly for programmers, who should prefer to be rational than superstitious.

It’s the same reason why scientists have by and large stopped explaining away the world with “God”. Saying that something in our natural world is “magic” or the work of a “God” is a cop-out. Why even study the world at all? We could just say it’s all hocus-pocus and never have to worry about it! The same idea can apply to programming as well.

I used to think that Ruby meta-programming was dark magic. I didn’t understand any of it and felt like I just couldn’t break through the barrier of clever one-liners and idioms, but I started to read the source code of Ruby projects that I used in my day job and side projects. I studied carefully, taking the time to understand even the most complex-looking constructions. I learned some things about Ruby that I didn’t know before and picked up some common patterns. Suddenly, Ruby made a lot more sense and my skill with it grew rapidly. Every day, I’m learning more and more.

So here’s the first part of the message that Giles was trying to deliver: Rails is not magic. It’s Ruby.

(There are also some supplementary thoughts about how, from a Lisp lover’s point of view, languages like Ruby and Python, even with all of their meta-programming power, might be annoying because there is still a subtle distinction between data and code.)

This is not to say that Rails is perfect or pure. The Rails team is making great efforts to bring in ideas from Merb to reduce some of the pain that developers feel when trying to go against the grain of Rails’ conventions. I am very much looking forward to Rails 3 and I think many others in the Rails developer community are too. But it is not “dark magic”; it is a tapestry of abstractions (albeit sometimes of the leaky variety) that are weaved together with clever Ruby programming. Maybe some of the code is too clever for its own good but it is a potent demonstration of just how expressive Ruby can be. But the upshot of Rails’ design is that, inevitably, something in Rails won’t behave the way you might desire it to and you will find yourself forced to dive into the source code of the framework to find out why.

While I don’t disagree with the notion that Rails could be documented a lot better, I’ve realized that source code is the most reliable form of documentation. API docs and tutorials and blog posts may be out of date or missing details, but the source code is the current set of instructions that is being given to the computer. It is always the most comprehensive and accurate picture of how the system works at any given moment. And, more frequently than ever, we have the power to dive into the source of the software we use to enhance our understanding where its documentation fails.

Now here comes the second part of what Giles was trying to say:

If you love Ruby (as even some anti-Rails folks do) but you’re vexed by Ruby “magic”, read the source. Study it carefully, ask for help if you need to, and contribute your findings back to the community. But don’t just dismiss it as magic, or you might be missing out on a chance to learn some incredibly useful and powerful things.