Review: Learning Dojo by Peter Svensson

… or How to Write a Good JavaScript Book

It’s widely known that the vast majority of JavaScript books that exist are bad. Unfortunately, I have another one to add to the list: Learning Dojo by Peter Svensson.

I fought with myself over whether or not it is a good idea to post this review. I’m afraid that this review may come across as an attack on the author, the publisher, or the reviewers of the book. Instead of looking at all of the errors in the book one-by-one, I am going to try to write an exhortatory post so I can better communicate what I would expect in any JavaScript book in this class.

To be fair, I don’t think that the blame for the book’s poor quality should be entirely on the author. From what I can gather simply from reading it, I would say this book was rushed and not properly reviewed for quality or accuracy. Also, I’m a purest when it comes to the web; so when I see [what I perceive to be] an outright dismissal of best practices, I start to get a little judgmental. Sorry, I can’t help it.

So, after over a month, I have finished reading the book cover-to-cover. I’ll admit that I part of the reason why it took me so long to get through the book was because I  lost interest about halfway through. Chapter 6, Layouts (linked below) is long, tedious and goes against nearly everything I stand for when it comes to building web pages. I simply had to keep putting the book down. Before I get ahead of myself, let me start off start off at the beginning and work our way down.

Source code should always be carefully formatted

Whenever someone asks me to critique a web site they have built, one of the first things I do is view the HTML source. If the developer has taken the time to make sure that the code indented properly and consistently spaced, I see that as someone who really cares about the quality of their project. I see it as a sign of a craftsman at work.

In the real world, this is a “nice to have” as it doesn’t really matter much — just as long as the page functions correctly, I don’t have much to complain about. In the world of tech books, however, properly formatted source code is a requirement. Remember, people learn from the source. Chances are, people will copy that down character-by-character and think that it’s the right way to do it.

Listen, JavaScript source code can be complex enough by itself. It’s an author’s responsibility to make sure that it’s as clear as possible so that good habit patterns are established from the jump. In nearly every source code listing in the book, I found something inconsistent, oddly spaced, full of errors, or simply impossible to read. This to me is completely unacceptable and was one of the first things I noticed while reading this book.

Even JavaScript books should encourage web standards

Almost every HTML document in the book was invalid. This was mainly due to the fact that Dojo itself encourages the use of custom attributes. Some may argue that there’s nothing wrong with this practice, especially when making use of a custom DOCTYPE. What’s worse is that the author made no effort to provide any alternative techniques let alone even discuss the dangers of deliberately writing invalid code. This may have been excusable ten years ago, but not in this day and age.

At the very least, I believe the author should have demonstrated an alternative technique for defining custom attributes — for example, using a combination of dojo.addOnLoad and setAttribute, or even better: not use custom attributes at all and use each respective dijit’s constructor.

eval is Evil

There is only one circumstance where the eval function should be used: parsing an Ajax response; and that’s only allowed after the response has been properly sanitized via a regular expression.

This is a concept which is well known and documented in every programming language with an eval function. Nothing further needs to be said about this.

JavaScript is deep; spend extra time on complex topics

Because I’m also working on a post where I explain closures in JavaScript, I was very pleased to see that the author had taken the time out to explain them in this book. Unfortunately, the explanation of closures in Chapter 2 left me more confused than when I had started — and I’m quite familiar with the topic.

Admittedly, the problem of JavaScript closures is two-fold: closures are incredibly abstract and secondly, almost nobody knows JavaScript’s full capabilities as a functional programming language. Source code helps to illuminate the complex topics, but a practical example should be carefully chosen. Two examples are given by the author, however one is broken and the other is completely misleading. This book is better off not even mentioning closures at all.

It also should be mentioned that your explanations should be technically correct. Let me quote the author’s explanation of how Ajax works:

In practices, what happens is that the browser opens a new iframe with zero height and width. Each iframe is capable of loading and posting data independently of each other, and so the accesses of the ‘invisible’ iframe will not affect the main page to be reloaded.

I’m not sure if the user was explaining how Dojo does Ajax or if he was trying to simplify the topic into familiar language, but the explanation is just wrong. This makes for a wonderful segue into the next, and equally important topic: proper terminology.

Never use improper terminology — ever

Programming is as much of a science as it is an art form, and as a result any sort of educational material should make use of proper terminology. In areas of introducing new concepts, it’s quite acceptable to use an analogy or reference another topic in order to build a frame of reference. For example, the author likens JavaScript objects to associative arrays. This is great because the name/value structure of objects in JavaScript are very similar to associative arrays; however, they are not the same thing. All throughout the book, the author uses the term “associative array” when he really means “use an object-literal as an associative array.”

In other instances, the terms “parameter”, “property”, and “attribute” are used interchangeably when referring to HTML attributes. Switching up vocabulary is just as dangerous as using incorrect terminology. Why? Because it makes you sound like you don’t know what you’re talking about. This is really bad when the people you teach start parroting this back.

Concluding Thoughts

There you have it, five simple things to keep in mind while reading this book or while attempting to write your own. I’ll say it again, I don’t want to attack anyone involved in the publishing of this book. That said, I won’t apologize for my response. The above mentioned topics are basic and there is simply no excuse for them to have slipped through the cracks.

At the time of this writing, absolutely no errata has been published for this book. This only adds to the reasons why I simply cannot recommend this book anyone, regardless skill level.