I’ve been reading (and writing) a lot of code recently and wanted to share a graphical technique for understanding an alien codebase.
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).
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?
- 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!