I finally had a bit of time to look under the hood of Bespin. Hacking around on a new piece of software is like raiding a candy store if you have a sweet tooth. Especially when it is as concise, well thought out, and implemented in JavaScript like Bespin.

What sealed the deal for me was the result I got when I applied a 10 minute inspect-search-edit-refresh technique I use when learning the ropes of a new architecture and implementation. Lets call this technique “dive and swim”.

Before I get into what got me excited I am going to give you an insight into how I approached this new candy store called Bespin.

Extra! Extra! Read all about it!

Before you dive into new code you are well advised to get your bearings first. By bearings I mean valuable facts about the application that give you a rough overview about what to expect. This is important because it reduces the likelyhood of running into dead ends when you investigate the code and can save you a lot of time.

Bearings for Bespin are things like:

• It’s all open source
• The client is written in JavaScript
• It has a client and server component
• It uses CANVAS to render it’s UI
• It has a grand vision

There are many sources you can use to get some important facts:

• Read the announcement
• Play with the demo
• Skim the documentation categories/headings
• Skim mailing list subjects (to determine aspects that excite people or common problem areas)
• Skim README files

The idea is to get a global picture of what to expect, not to actually study anything in detail unless something catches your interest of course. Now bearings are useless if you don’t know how to interpret them. That is where your experience and intuition come into play. The more you have the faster you can move to the point where you can skip a lot of these steps - because software development is an art, but also a science and with science comes true and tried techniques/concepts/standards that span all decent implementations.

Going back to the Bespin bearings from above, filtered through my experience I get:

• It’s all open source - You can download and play with the whole system, discuss it with others, search online for blog posts, read mailing lists etc…
• The client is written in JavaScript - The client can be extended and monkey patched easily and refreshed in the browser to see the changes.
• It has a client and server component - The server component is likely not implemented in JavaScript as server-side javascript is still too new to be used as the primary backend for a project that aims to gain a large audience fast. So the server is written in a different language than the client leading to the conclusion that some well-known protocol that is cross-language is likely used to link the two.
• It uses CANVAS to render it’s UI - see below
• It has a grand vision - The developers put a lot of thought into it (I should find well-structured code) as only a fool would set grand goals and publicly parade them without having the experience, insight, research, passion and backing to actually follow through.

While the bearings are objective and subjective facts your interpretations are assumptions you carry into the candy store and validate as you raid the shelves (read files).

The CANVAS Bearing

For me the most interesting bearing and reason for further investigation (other than the explosive welcome Bespin has received) was the fact that is uses the CANVAS HTML element to render it’s User Interface. Why is the whole CANVAS thing so interesting? Because CANVAS has been lurking in the shadows of HTML+CSS for a while and until now never showed itself in this way; maybe for games; but not for a component-based UI with user interaction (at least to the best of my knowledge).

Why is this whole CANVAS UI implementation so interesting to me? About 10 years ago I wrote something similar using Java. At the time SWING just came out, was not known to me, not practical to use yet or did not do what I needed at the time (I cannot remember) so I ended up writing my own UI toolkit.

I created classes for different UI components and layout managers that rendered pixels into a coordinate system that was displayed to the user as an image. Mouse events on the image were captured and dispatched to the appropriate UI component that was rendered at the given coordinates. The whole UI layout and components were defined using an XML document and each component had a data provider class that buffered data access to underlying data sources. Components were linked and business logic added via an event system using listeners and dispatchers.

From what I remember I spent a lot of time on this. At least 6 months of development while studying at university and the result looked and worked pretty nice. Here is a few screenshots I was able to dig up. Have not found the code yet.

When looking at Bespin I used my past experience in writing a similar UI toolkit as a map so I knew what to look for. I roughly knew what was needed to implement the Bespin UI functionality and had a shortlist of concepts in mind of how the whole app was put together.

Having such past experience gave me an unfair advantage in this case. It goes to show that any experimentation you do in your early years of development may potentially pay off in future.

Now I don’t want to promise something I cannot deliver on but I would not be surprised if I ended up putting some real time into hacking around with the CANVAS UI Toolkit in Bespin, pulling it out of Bespin and looking at how I can expand on it and incorporate it into some of my other projects.

(Inspect<->Search)-(Edit<->Refresh)

Once you found your bearings and formed your assumptions you are ready to dive into the code. When using the dive and swim technique you are best advised to use it on a working install of the app. It has to be working because you are going to make edits to the code and then refresh/restart the app to see what changed.

Inspect

Start by asking yourself a question. Something like: How can I make a simple change to the code that will change something in the UI?

Combine that with your asumptions and you get something like: Let’s look for the generic UI toolkit classes. You arrive at this action step because you know what is likely needed to render the UI and you know how it is likely implemented.

Browse the code tree in your IDE’s Project Explorer (I use Ecplise) and open files that based on their name and directory could have something to do with the UI toolkit. When you find something that looks like it is related look for variable, class, object member or function/method names that are likely part of a public API of the UI toolkit and used wherever the application defines it’s UI.

For instance I found the Scrollbar variable/class in /frontend/js/th/components.js

Search

Next you open a search dialog box that can search across all files in the project and input your Scrollbar keyword. The search result in Ecplise is nice because it shows you the files containing matches and the location of the files in the project directory structure. With every search you do you will get more familiar with the way the code is structured as the results show you where and how (once you inspect the result files and matches) the public API of different components is used within the app.

Doing this search & inspect on Bespin for example revealed to me that it looks like the Scrollbar defined as part of the UI toolkit is used for other UI toolkit components but not for the editor which seems to implement it’s own scrollbar.

When I was skimming /frontend/js/editor/editor.js I saw a variable that caught my attention as a potentical candidate I can edit to create a simple change in the UI (my original objective): this.GUTTER_WIDTH in Bespin.Editor.UI.

Edit

Make a small change in the code. When setting a variable to a new value, choose a value that you think will result in a noticable difference but one that you think still falls within the acceptable value range of the variable that may or may not be explicitly validated. You can also modify methods, add alert() calls or log to Firebug depending on what you are trying to figure out.

I changed the value of GUTTER_WIDTH from 54 to 34.

Refresh

The final step is to restart the application. Since Bespin is implemented using JavaScript this is really easy and requires only a refresh of the page. Look for the change you intended on making. If you can find it your quest was successful, if not you will have to trace the code a bit more to see what went wrong.

I was very happy when I saw the gutter shrink in size after a quick flicker of the UI (the refresh is fast which helps a lot in speeding up your edit<->refresh iterations). This humble result was enough to get me excited because after only investing 10 minutes I got a result I expected. Going into this I had an expectation of how easy it should be but nothing prepares you for how you feel when it actually is that simple, works and just feels right.

In Conclusion

There are many ways to go about learning the code of a new application. I shared with you a technique I have developed over the years that has served me well and got me results fast in short periods of time. It works particularly well with JavaScript and more generally scripting languages as you can search-edit-refresh the application in a matter of seconds.

If you are interested in Firefox extension development I highly recommend applying this technique to see how it works for you when learning from other people’s extensions because it seems to be particularly effective. I found that out while developing FirePHP where I needed to learn the Firebug code.

Remember that the dive and swim technique is an iterative process. You need to stay flexible and follow your intution and whatever catches your attention during the inspect<->search iterations.