Its been about a year since I added my first, and to date only, video to YouTube. The project was a Lego marble ladder machine. I’m not usually much of a measurer but I thought I would jot down some of the stats.

It has been just over a year (one year and 3 days) and it has been viewed 29,903 times. It has four stars with 61 ratings, 44 comments and 5 links. It was picked up on the Fascinating LEGO Model of the Day blog.

Is 29,903 a lot of views for a year? Probably not, but its all relative. Some YouTube videos get more than that in a day (I don’t know for sure but seems like a safe bet). However, far more people got to see it on YouTube than in my home.

I really don’t know where my time goes. I thought I would have completed at least one more Lego project in the past year but I haven’t.

Yesterday I attended a one day course, Presenting Data and Information given by Edward Tufte. It was only a few months ago that I heard of him when I saw the term sparklines and was trying to figure out what that was. Then my friend David told me about this course. I thought it would be interesting to me because I have a strong interest in user interface, usability, and data visualization (although not specifically in statistical data). My employer, BEA, was nice enough to send me.

There were a large number of people at the course. It was in one of those hotel function rooms that could easily be divided into four. The room was wider than it was deep and there were two large screens on either side. It seemed clear Edward would be speaking from the middle of them. I usually like to sit up front in presentations so I can easily see the screen. A rainy morning commute into Boston kept me from arriving early so there weren’t many good seats left. I picked one in the first row right in front of one of those big screens. I thought “I may not be able to see him well but at least I’ll have no problem seeing all the information up on the screen”. Being in front of the screen was of no value what so ever. They were hardly used. This makes perfect sense by the end of the day.

Everything I needed to see was right in front of me in the four books you receive as part of attending the course. He is a clear speaker. The sound system was excellent. The screens were used just the right amount - for a few animations and video, and the occasional graphic not in one of the books. They were turned off when not in use.

He practices what he preaches. No Power Point. Use the high resolution medium of print for your data rather than the low resolution computer screen. In this case the “handouts” were his books. Have people read the data before the presentation starts. There was a reading period and assignment prior to the course starting.

It was a very interesting course and I enjoyed it completely.

I just read a very interesting article called Secure String Interpolation in JS that got me thinking about rendering in StringTemplate. I don’t follow the caja project but it looks interesting. I found the article linked from John Resig’s blog.

Script injection in web applications, which also goes by the name XSS (Cross Site Scripting), is a serious and common security problem. It arises when the application does not appropriately escape data that comes from an untrusted source. The data could contain malicious JavaScript that would get executed. If developers are burdened with remembering to escape each and every instance of data they will eventually forget or make a mistake and a security hole will result. One main point of the article is that string interpolation should be automatically secure — it should do the right escaping for you.

Every now and again the issue of how to escape special characters when generating HTML files comes up on the StringTemplate mailing list. The answer is very straight forward - write a renderer. My main point, which I’ll get to eventually, is about the details of the renderer.

The author of the above article distinguishes string interpolation from “full blown” templating languages. JSP, PHP, and XSL were given as examples. Three problems with full blown templating languages were given (folks familiar with StringTemplate know there are more):

1. They do nothing to help solve the escaping problem.
2. They are verbose and add lots of boiler plate.
3. They don’t make simple things simple.

I think StringTemplate holds up well against these complaints. The renders can do escaping. The simple templates (.st files) have no boiler plate at all and the group files (.stg) add only a little. Lastly, it doesn’t get much simpler than “Hello $name$!”.

The most important issue and the one the article is really about is number one — escaping.

On an HTML page what characters need to be escaped depends on the context: element content, attribute value, JavaScript, and URIs. StringTemplate rendering assumes a single rendering context. As of StringTemplate version 3.1 the format option can be used to specify a specific rendering (format). The trouble with this is that the template writer must be aware of the different contexts and what format to use in each. An alternative is to come up with a one size fits all escaping renderer. This will end up escaping more than it needs to. There may be some fringe cases where this could cause problems.

The thing I found most interesting about the approach given in the article is that the context scanner keeps track of the current context in the output so that the escaper can do the right escaping according to the context. To put this in StringTemplate terms the output after rendering would be feed into a parser that tracks changes in context (element to attribute value to JavaScript to element content etc.) and informs the renderer(s) of the current context.

You can still use the format option or other custom renderers to specify how the data is turned into a string (for example a number could be currency or a percentage). This is something that the template author is expected to know. It seems reasonable to me that it would be better if the author didn’t need to understand the intricate escaping rules of web pages.

A key innovation of StringTemplate is the identification of the Model-View-Controller-Renderer pattern — that there is a renderer distinct from the view. (Read about MVCR here.) Now I am seeing the render as two distinct pieces. There is the format renderer and the escaping renderer. The former is concerned with if negative 23 should be output as (23) or -23. The latter is concerned with if single quote should be output as ‘ or ' The format renderer runs first and passes its output to the escaping renderer.

The reason it makes sense to think of two different renderers is that they each have different masters. The format renderer is directed by the needs of the application, the locale and perhaps presentation directed formatting with the format option. The escaping renderer’s function is determined by the language of the output: SQL, HTML, XML or just the text of an email message.

Other thoughts and observations:

Is there a need for a JavaScript implementation of StringTemplate? As it becomes more common to move the model, view and controller to the client there could be a role for it. It could also run server side in Rhino. Although the author of the article states that it is not a goal to create a template language I wonder if the extra capabilities of StringTemplate would be welcome.

The method used in the article for implementing auditable exemptions (cases where you know the data is safe and you don’t want it escaped) is the same as would be done in StringTemplate. Just wrap the data in a type that returns the raw string when rendered.

In the article a simple FSM was used to parse the HTML. Only an excerpt of the code was shown and I didn’t bother to download it and look deeper. It seems to me that the output HTML needs to be well formed otherwise the parser would be very complicated if it has to deal with the tag soup that browsers deal with.

This is now at least the fourth time I’ve seen a parser written in JavaScript so I think there could be a need for a JavaScript backend for ANTLR. I would have liked to create a l-system language parser in JavaScript for a recent project of mine. Is there already an ANTLR for JavaScript that I don’t know about?

Does anyone else think that it would be useful/feasible to have a HTML escaping renderer (that does the correct escaping in automatically) as part of the StringTemplate library?

Recently I had some not so nice things to say about jQueryUI while still professing my love for jQuery. What didn’t come across in that post is that I am hopeful that jQueryUI will become as great as jQuery.

Now it seems I have good reason to be hopeful. John Resig tells us the good news that Paul Bakaus (the lead developer) now works full time on jQueryUI at Liferay and that a new release is due out soon.

While playing with Scratch I was thinking about what kinds of things would make good Scratch projects. I have had an interest in L-systems for a long time now but never did more than read about them and look at the pretty pictures. I thought scratch might motivate me to do something in this area but I quickly realized with Scratch’s lack of data structures (besides the 2d drawing surface) and argument passing it would take all the fun out of doing an L-system implementation. Sure, people have come up with ways of drawing fractals in Scratch but these are fixed algorithms usually at a specific generation. I have not yet seen an L-system implementation in Scratch.

About a month later I went to the ajax experience conference and learned about the new HTML canvas element among other things. I wanted a project to get practice writing JavaScript, more experience with using jQuery, and to try out jQueryUI and canvas. L-systems seemed like a great project for this purpose.

Before I get to my project here is a real quick definition of what an L-System is. A Lindenmayer system (L-system for short), named after biologist Aristid Lindenmeyer, is a rewriting system. It takes a list of symbols and repeatedly generates a new list of symbols by following a set of rules. Each new list of symbols is called a generation. The symbols can be given a graphical representation to produce an image algorithmically. The beauty of L-systems is that with just a few symbols and rules amazingly complex images can be created. L-systems were developed to model plants but can also draw fractals. More information is available from the links above and from the lsystem.js documentation.

My project, L-system.html, is a serverless web application for exploring a number of plant and fractal models created with L-systems. You select a model, change its parameters such as angle or distance depending on the model, set the number of generations then press the play button to see it drawn.

Being able to adjust the parameters of a model helps to understand it. When you see a fractal of some reasonably high number of generations it is not always clear what process gives rise to it. Stepping through from the zeroth to first and second generation of a fractal really helps to visualize the rule that makes the fractal what it is.

L-system.html is not very fancy or even complete. The main purpose for me was learning canvas, jQuery, and jQueryUI. It makes use of two reusable JavaScript libraries that I wrote:

• lsystem.js – a L-system library that supports parametric or non-parametric, deterministic or non-deterministic, context sensitive or context free, and branching or flat models.
• turtle.js – A 2d turtle graphics library on top of the HTML canvas API.

Both of these are open source with a BSD license if you care to use them. They can be used together or independently. You can download the whole project. If you make improvements to them or have suggestions I’d love to hear about it.

The rest of this post covers what I discovered along the way.

First I have to say I’m impressed with canvas and its capabilities. Its not as full featured as most mature graphics libraries and there are a few features that are not supported on all browsers but it opens up another area to web applications (without having to resort to Flash) that was previously only found in desktop applications. People are doing cool things with it already. Support for IE is accomplished with explorercanvas from Google. I have tested my project on Firefox 2, IE 7, Opera 9.24 and Safari 3beta (on Windows) and it works well except that the save functionality doesn’t work in Safari or IE. Also I have noticed IE to be slower than the others but have not done any rigorous timing.

Thanks to Canvas Paint (a canvas implementation of Microsoft Paint) for the technique for saving canvas images.

L-system.html is an example of a serverless web application. Its an application because it is interactive and does something at least a little interesting or useful. Its a web application because it runs in a web browser. Serverless is a somewhat new category of web application. It basically means that none of the application behavior is running on a server. A web server may be serving the HTML and related resources but there is no servlet, or PHP script, etc. A server may be providing raw data or persisting data (like the Amazon S3 service) but this is just data storage or acquisition and often the servers or services are not even owned by the creator of the application. In some cases the application can just be an HTML file on your local file system. L-system.html can run this way. An even cooler example of the kind of interesting things that can be done without a server is TiddlyWiki - a serverless wiki.

After working more with jQuery I’m convinced that this is the way I want to write JavaScript and to work with the DOM. However I’m not anywhere near as impressed with jQueryUI. It just doesn’t seem ready for prime time. I only wanted a few UI elements: a slider, a dialog, a progress control and a color picker. There is no progress control or color picker in jQueryUI although there are plugins for color pickers and maybe a progress control as well. I thought it would be best to stick to the official UI widgets. I struggled to learn the UI widgets and get them to work the way I wanted. I needed to read the source as well as the documentation to figure them out.

The first problem I ran into was with the slider on on IE 6 and 7. I found a bug report that said the problem was fixed in the latest. After downloading the latest from the SVN source repository the problem was indeed fixed.

I wanted to be able to move the slider with the right and left arrow keys and to show that the slider had focus. I know that jQueryUI doesn’t have full accessibility support yet, but keyboard support seemed like it should work for a control like slider. I noticed some code to turn on keyboard support when webforms (not sure what that is) is present. This helped me figure out how to get it working the way I wanted. You can tab to or click on the slider to give it focus and then use the arrow keys to move the slider.

One thing that bugs me about some ajax apps is that they break the back button. I really wanted to get back button history working with jQuery in this project. At the ajax experience conference I saw the history plugin demonstrated and it looked so easy. So far my attempts to get it working have failed. The history plugin seems like it would be easy to use with the tab control but i’m not using the tab control. Then I read that the new tab control in jQueryUI doesn’t work with the history plugin. There is a mention that the history plugin needs to be rewritten but no time frame for when it will be available. Since I’m not using tabs it may be possible to get the current history plugin working but I haven’t figured it out yet.

My next problem was with the dialog control. I found that I could end up with multiple copies of the dialog displayed. I decided to try the latest version from SVN like I did with the slider. I did manage to solve my problem by using the new dialogInit method. (There may have been another way.) The trouble is that at the time I got the latest version of dialog the mouse management was rewritten which broke the slider and resizing of dialogs. As of this writing they still are not fixed. There may be some set of source versions that will solve both my slider and dialog problems but I don’t have time to find it. So at this point the sliders do not move with the mouse (you get a JavaScript error). I’ll just have to wait for the jQueryUI mouse implementation to get finished.

I noticed that some of the jQueryUI documentation (at least the examples) are in advance of the current 1.0 release. For example, the dialogInit method was shown in one of the dialog examples even thought it is not in the 1.0 release.

There is no progress control in the jQueryUI so I made my own. The next step will be to learn how to turn it into a plugin.

Along the way I found a number of useful tools and practices for writing JavaScript

• Firebug is a very good tool. I knew that already but with this project I used the profiler for the first time. The profiler is very easy to use and helped me to improve the performance of the L-system algorithm. I also used the console log, which Firebug lite makes work cross browser.
• I’m using JSLint from an ant task and it has found some problems. I described the technique for ant integration here.
• I used jsdoc-toolkit to generate the library documentation. This tool is very easy to use and produces nice results. Since the JavaScript is going to get minified anyway I think it is a good idea to keep the documentation in the source.
• For testing the 2 library modules I used jsunit. Actually I only used the assertion functions from the core. This looks like it could be a good tool but I need to learn more about how to use it effectively.
• I use just the CSS library from YUI.
• To build the final html as well as the aggregated and minified resources I use ant, yui compressor, and STST. One thing I noticed is that yui compressor catches some JavaScript problems that JSLint did not.

After I was just about done with this project I discovered that someone else created a canvas L-system implementation LSys/JS. Although it doesn’t support as many kinds of L-systems it does allow you to enter your own. Also it does not have a reusable library layer.

If you have read this far without trying it out you should take a look at L-system.html now. If you want to add your own L-system models you can download the project and modify the lsystem.html file. If you come up with a cool model leave a comment with a link to it.

Today I’m going to rant about something that really bugs me - commenting out code. Just about everywhere I have worked and in most code I have read I have found code that has been commented out. What is it that possesses people to do this? Why is it so prevalent? Is this practice actively being taught and recommended?

If code should be written as if for humans to read and incidentally for computers to translate then commented out code is worse than useless because it slows down and confuses the human reader.

Imagine reading a book or article with text crossed out like this. It would leave you wondering if you should be reading these sections or not. Why didn’t the author just get rid of the text all together?

When I see commented out code I don’t know if the person who did it was just forgetful, uncertain of what he or she was doing or doesn’t use or trust source control to do its job.

During development it can be useful to temporarily comment out some code to see the effect removing or replacing it will have but this temporary experiment should never be checked in.

Here are some things I do to make sure I don’t forget to remove or uncomment code in this situation:

• For real quick tests I’ll delete or cut the code and let the editor undo or paste buffer remember it for me. This has the risk of losing the old code if the editor or computer crashes but you can always get it back from source control if it was previously checked in.
• I always add a marker to the comment such as “todo” or three x’s so that I can easily find things I forgot to cleanup.
• Before checking in I diff all files against the head revision looking for the marker or other undesired or accidental changes

If you’re not sure of your changes keep reading and testing until you are sure. Then delete that old code. If it helps imagine that the code is cheese and wrapping it in comments is like leaving it out of the fridge. Its going to get smelly and you don’t want your code to stink do you?

You really don’t need the old code stuck in comments. Source control does a much better job of showing you what the code used to look like. It is more trustworthy and can tell you more information such as who made the change and when. Depending on the source control system the changes can be correlated with related changes over many files.

Are there any exceptions - any legitimate reasons for having code in comments? Just a few but most of what I come across doesn’t fall into these categories.

Code that enables a special debugging, testing or profiling mode can be left in to make it easy to re-enable that mode later. The code should have a comment such as “uncomment the following line to enable debugging”. Often there are better ways to do this. It may be useful to have a runtime switch to enable the code or if your language has ifdefs they can be used to create a variant of your program. AOP or code generation may also be appropriate.

Sometimes you may add some code that depends on some other code that isn’t ready yet. You can test your code with a test harness but it can’t be used until the other code is available. In this case there should be a comment such as “uncomment this block once the foo modules is ready”. Again there are sometimes better ways to handle this situation such as creating a branch in source control for the unfinished work with stubs in place.

Another possible reason for leaving in the commented code, that I don’t really agree with, is as a cautionary statement. As if to say don’t think of changing the code back to this because it used to be this way and I decided that it didn’t work out so well. In this case it is much better to replace the code with a human readable comment about what should or should not be done in this context. For example suppose you have code like this

  resourceA.lock();
  int foo = bar();
  ...

Someone finds a deadlock condition due to calling bar. So they comment out the call.

  resourceA.lock();
  // int foo = bar();
  ...

This is bad because future maintainers have no idea why that was done. The following is a little better.

  resourceA.lock();
  // this was causing a deadlock sometimes
  // int foo = bar();
  ...

But this is even better still.

  resourceA.lock();
  // be sure not to call any functions such as bar that try to lock additional resources
  ...

The bottom line is don’t check in commented out code and if you do it must have a human readable statement as to why it is being left in. All of the above apply to ifdef-ed out code as well.