May 24 2008
7 Comments
By Caleb Johnston Architecture, AS3, Flash

Code Documentation

by

I recently finished a campaign site for Starbucks in order to promote the Starbucks brand of coffee available in grocery stores. The address is www.starbuckscoffeeathome.com. It was a very pleasant project to work on, but it was also quite fast paced. The project also remained in a state of high flux until launch. These two aspects combined made it nearly impossible to keep accurate comments on my code. So, after this project was complete I decided to re-write my UML for it based on the way it ended up (rather than the way I originally designed it). After doing so I’ve come to believe this serves as better and more digestible documentation for a developer than most inline commenting. Thats not to say it would completely replace code commenting, but I feel as though its more useful for another developer to see in order to get a grasp on how a body of code works. For this diagram I didn’t have the right tools available to me immediately so I used what I had (which was Adobe Illustrator). This required a greater investment of time, but the time consumed was likely on par with the amount of time required to produce sufficient written documention. For most practical situations, a simple sketch would suffice. Have a look at the diagram (and submit your critiques if you like).

Download the Starbucks basic class UML (PDF).

I’ve also conducted a certain amount of performance profiling that I will write up in the near future.

  • http://blog.paoloiulita.it Paolo Iulita

    hey man that’s nice! a cool diagram to study in order to see how different people approaches different type of solutions.

    I have only two questions:

    1) why haven’t you created an AbstractView class and then extended it for all of your view classes?

    2) are the controller classes singelton?

    thanks and again congratulations for sharing this with us.

    Paolo

  • http://www.calebjohnston.com Caleb Johnston

    Thanks for writing Paolo. I will try and keep my response short but complete.
    1) Actionscript doesn’t formally support abstract classes. Mims has provided a work-around example for building your own abstract class functionality. You can read that post here: http://blog.extends.eventdispatcher.org/mims/abstract-classes-in-as3/
    However its my personal preference to use the existing language features as they are unless I truly need the additional organizational feature of something thats not native. Again this is my preference. Also, for my purposes there is no default behavior needed for any of my view classes other than what is provided in the base MovieClip and Sprite classes. So I think an abstract class is a bit unnecessary.
    2) Yes. However, they interact with other classes almost exclusively through event listeners. Although in the case of the NavigationController, some listeners are added like so: NavigationController.getInstance().addEventListener(…);

    Perhaps I can amend the diagram to show which classes are singletons. Thanks again for your feedback!

  • http://blog.paoloiulita.it Paolo Iulita

    and you gained it! short but complete.
    I’ll dive on Absract Classes Issues and workarounds :)
    About singleton, I asked just for being secure, since often UML diagram reports singleton classes.

    Good job and thanks again!

  • Pingback: dispatchEvent() / Flash Site Experience Profile

  • shaun

    thanks for sharing your application structure – I find it much more useful to look at the big picture than read through specific code snippets. I wish more developers would share their UML.. application design is certainly more challenging than writing code! thanks again. s

  • http://interactivesection.wordpress.com/ Hu

    Hi Caleb, thank you so much for this post. It is one of the most helpful code posts that I have read.

    I recommend EnterpriseArchitect for UML purposes, if you are on a PC. The generation of UML is almost automatic and if you start up UML diagrams, it generates the AS files automatically, which saves some tedious and boring typing work.

    My question about your UML:
    1. is there a Main Model that you keep track of all the data? where do the AudioModel, CopyModel, EnvironmentModel get their data from? XML files? I feel the structure of model is also key to a website.
    2. Is there anyway you can list the public methods (especially getters and setters) under the classes?
    3. Is there a reason you separate “Manager” from “Controller”? What is the key difference of the two?

    Good jobs.

  • http://www.calebjohnston.com Caleb Johnston

    1. There is no ‘Main Model’. Each model class is usually only a collection of static constant values. However if the values must contain external data then they are variables instead. Those variables are then manually initialized when the external data has been loaded.
    2. This can be done but currently, time will not permit!
    3. All controllers are singletons that are very high-level in that they don’t perform a lot of work other than processing and dispatching events. However, the only managers that are singletons are the AudioManager and the LinkManager. The managers handle more of the raw work. An example of this relationship is the following:
    LoadController dispatches events to and process events from 3 LoadManagers. But LoadManagers actually perform the real loading of data and all decision making that is involved.

    In terms of MVC design -both can be considered controllers but in terms of the architecture of the site, there is a difference in roles. The primary reason they’re separated is so that I can easily re-use the managers for other projects. The controllers would be far less useful elsewhere.