For the past year I’ve been working on a complicated Javascript project that includes, among other things, an “agent simulation engine” that allows students to program an “agent template” where they could:

• name a property to store a value
• read and write the named property
• conditionally execute code based on the value of a property
• generate any number of “agent instances” from the template and run the simulation

This did not seem difficult at first, as we already had a simulation engine that was already built around these principles. I then ran right into the main problem: while we could easily write this kind of code ourselves in Javascript, the implicit requirement was that students could define the first three operations IN ANY ORDER within the context of our simulation engine. That meant I needed to write some kind of scripting language or sequencing method on top of it because the students don’t have access to Javascript, and we can’t generate compiled Javascript code from source in the browser due to hard security constraints.

There are a lot of things happening in this simulation engine already, and I was having trouble “reasoning” about the system. Not only did I have to think of sequencing the simulation engine, but I also had to sequence the student script engine on top of this sequence. I was getting lost in the wheels within wheels within wheels. So I made a bunch of maps to get the systems out of my head and onto paper so I could reason by mentally visiting the system from different points of view. I used the web-based app Whimsical because it’s awesomely well-designed and lets me get really fussy about lining things up.

Thinking in Whimsical

Thinking-through the problem was very hard for me, and originally I berated myself for being so slow on the uptake. However, the act of making diagrams helped clarify my thinking, and once I had it all in a visual form I could start to see what I was missing and where I was going in circles. Whimsical’s interface is streamlined enough to let me THINK, GRAPH, and REFACTOR as fast as I could. I can’t think of another tool that works as well while making diagrams that look pretty good. Let’s have a look at them!

SYSTEM PHASES

This is a diagram of the high-level “phases of operation” of the running application. This was just me dumping some kind of structure so I could just see something to visually “run” the app.

SYSTEM FLOWCHART

These are the main “workflows”, which also helped me “visually run” the app and imagine what is going on.

SYSTEM TYPES

The object hierarchy was also really unclear in my head, because there was just too many things to remember. Making this diagram helped me see everything I had available, and also helped me name things consistently.

SYSTEM MODULES

This diagram started out as a map of the source code directory structure, but it also became a guide to help see the types of source files. I wanted to make sure that related files were close together in the directory structure, and that the object hierarchy itself could be INFERRED from the directory structure. In other words, the directory structure should tell you how the system is functionally organized using consistent language.

DATA ARCHITECTURE

Once I got the scripting engine working (I ended up implementing a stack machine, but not a parser) I needed to see how this app communicated with all the other systems.

Evaluation

I tried to not fritter away too much time on the documentation without shortchanging my thinking process. That said, this still took 15+ hours to do over a couple of weeks as I refactored and renamed existing code to fit the module diagram, then added the script engine elements using the other diagrams as a guide. This is a project that needs to move fast so we can test ideas sooner than later, and it was difficult to force myself to diagram because it was already taking WAAAAY longer than I wanted. On the other hand, things work now BECAUSE of these diagrams, and the overall design

I have mixed feelings about making these diagrams because they remind me how bad my memory is, which makes me feel like a poor programmer. This is a constant frustration, not being able to hold enough detail in my head so I can write clean code quickly. On the other hand, taking the time to create clarity is a necessary part of my general working process. In terms of the programming work, it feels like a side diversion because the medium is different (graphic design) and it does not directly contribute to the bottom line (working code in front of kids).

If there are any freelance Javascript programmers out there who find this kind of stuff interesting, we are looking for people to help us with our projects :-) Thanks for checking out the diagrams!