- 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
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!
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.
These are the main “workflows”, which also helped me “visually run” the app and imagine what is going on.
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.
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.
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.
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).