The visual anatomy of (see below for complete diagram)

I’ve been reading (and writing) a lot of code recently and wanted to share a graphical technique for understanding an alien codebase.

Code can be hard to follow, especially if you didn’t write it, and even more so if you are new to a language. Web apps are particularly hard to follow since they consist of several layers, each containing multiple technologies (HTML, CSS, Javascript, plus the intricacies of whichever MVC web framework you use).

I’ve been trying to get back into programming recently with Python and Django. To that end I’ve been doing a number of online tutorials. I find these easiest to follow when the tutorial guides you, incrementally, through the writing of an app so you can grasp the code a piece at a time. A couple of my favourite tutorials on this “incremental” type are James McGaw’s Beginning Django E-Commerce, and Ayman Hourieh’s Django 1.0 Web Development. The catch is that such a tutorial takes a long time, both to read and to write. Its also hard to get a quick overview! Call me impatient (-;

Other tutorials throw you right in andpresent a ready-built web app. An excellent example of this is John Jarvis’ Django/Jquery tutorial – Making a Flashcard Game. John introduces a whole suite of web technologies – Django, Jquery, HTML and CSS, tied together with ajax calls, JSON, Django templates and Dynamic HTML. Its a lot to take in, and John does a fine job explaining it. However, I still found myself losing the plot in the blog posts, and eventually ended up printing out the code, scribbling all over it, and sketching an intricate diagram of how all the pieces fit together. It was only when I had a complete diagram of the flow from initial load to Game Over that I started to get it.

You can see a (slightly tidier) version of my diagram below. Its not meant to be a complete representation of the codebase, but it does help you grok how the game flow propagates left-right and back again through the layers (HTML/CSS – Jquery and click handlers – ajax calls – Django views, templates and models).

A visual anatomy of the Django/Jquery Flashcard game (click pic for full size PNG)

If you are struggling with a codebase, give it a go. It does take a significant amount of time, but should greatly improve your understanding. If you are learning Django, definitely check out John’s Making a Flashcard Game tutorial. I hope this diagram helps you follow along more easily. If you are writing a tutorial, or documenting a codebase, consider throwing a diagram in!

Here are a few of the key concepts which sketching up a diagram like this helped make a lot clearer for me. I’m sure they are obvious to you old-hands out there, but they weren’t to me. Perhaps they aren’t to you?

  • Many newbie web apps consist of distinct calls to the server to display separate web pages. In contrast, here there is one web page, consisting of a framework of DIV elements which are revealed and hidden in turn as the user navigates through the flow. The hiding and showing is done by Dynamic HTML controlled (mostly) by client-side Javascript.
  • Much of the game logic is in Javascript, a language which does not have the most intuitive syntax. Sketching out the flow reveals the intertwined set of click handlers and functions which make the game work. Huh, Javascript isn’t actually that nasty!
  • One exception to the above is that the “Game Over” logic on whether to display a new High Score is contained in a Django template.
  • I’m a UX person. I like to track a user engagement from start to finish. Try doing this in the code. Yuck! Here you can see it at a glance.
  • Some of the JQuery game logic hits the Django back-end, however the main game loop does not.
  • Not all AJAX calls/responses are the same! Some return JSON, some return HTML of ┬ápart – or all – of a page. Again seeing some examples of this visually laid out in the overall application flow – helped make things clear.

Disclaimer: this posting is completely based on John Jarvis’s excellent Django/JQuery web tutorial. Go do it!