Diagram that could explain a state machine's code?

Question

We have a lot of concepts in making diagrams like UML and flowcharting or just making up whatever boxes-and-arrows combination works at the time, but I'm looking at doing a visual diagram on something that's actually really complex.

State machines like those that parse HTML or regular expressions tend to be very long and complicated bits of code.

For example, this is the stateLoop for FireFox 9 beta. It's actually generated by another file, but this is the code that runs.

How can I diagram something with the complexity of this in a way that explains flow of the code without taking it to a level where I draw every single line-of-code into it's own box on a flowchart?

I don't want to draw "Invoke loop, then return" but I don't want to explain every last detail.

What kind of graph is suitable to do this? Is there already something out there similar to this? Just an example of how to do this without going overboard in complexity or too-high-level is really what I want.

---

If you don't feel like looking at the code, basically it's 70 different state flags that could occur, inside an infinite loop that exists to a label based on some conditions, each flag has it's own infinite loop that exists to a label somewhere, and each of those loops has checks for different types of chars, which then runs off into various other methods.

Answer 1

You probably will want either a full traditional state diagram or a summary pseudo-state diagram.

The full diagram would have a state circle for each of the (in your example) 72 states, and each of the transitions (including self loops). Such a diagram is good for documentation and study for modifications. It is easier to deal with than the C code as it suppresses the irrelevant verbiage.

A summary diagram would be better for an introduction to the state machine code. It would require you to figure out some "super states" that represent groups of real states. This is often not too hard. In your example, it looks like the states with the "NS_HTML5TOKENIZER_COMMENT" name prefix can be grouped together, for instance. So in your diagram you would have one "comment parsing" super state to represent these 6 six real states. Then you make a fairly normal state diagram using these super states, showing the major transitions (or all, if you want accuracy) between the super states. This reduces the complexity of the diagram and show the major functions going on in the machine.

Answer 2

For something that long, you're best bet is to create a dynamic state diagram. (Yay for computers!) I have never seen one, but it's easy enough to imagine a debugger-like view of the diagram where you have "watch" variables to track the current state while you make choices of which state to examine. It would end up allowing you to see all of one state on-screen and understand things by watching what happens when things change.

It could be a bit of work, and someone may have created it before. I just hope the idea helps.

Answer 3

How can I diagram something with the complexity of this in a way that explains flow of the code without taking it to a level where I draw every single line-of-code into it's own box on a flowchart?

I would suggest that you define the purpose of the diagram and the scope of detail you want to provide. You either want a precise diagram or an overview diagram.

Diagrams reflecting precise information usually end up messy. To overcome diagram complexity, you would generally do this:

Break the state flow into separate logical pieces with clear start and end. Use state machine chart to show each logical set. Sort the sets by either start or end state. This will show the flow of state (but not the code). The State Machine diagram suggested by other contributors to this post is the only way to precisely represent state change visually.

Alternatively, use Pseudo code with rules table. Rules table reduce the complexity of the text significantly (I wish programming languages could implement then in their editors). This combination will show program flow and rules for arriving to a given state but won't give an obvious visual state transition flow.

If you are providing an overview diagram, you may choose to show the major states on a State Machine diagram.

Edit: Another way to represent this kind of information,is by using a table/matrix. Show each state in a separate column and each state in a separate row of the matrix. The intersection represents the conditions under which the transition occurs. Empty cells indicate that there is no state transition between the intersecting states. To show transition direction define 2 colors. One for transition from row value to column value and another to represent transition from column value to row value. The matrix option proposed here can be used with all above mentioned suggestions. if you add a number to cells where transitions occur, you could then show a flow of transitions (not shown in the example).

Answer 4

a simple state diagram would do if it doesn't become too large

however you can simplify it a bit when by making actions that are nearly the same but for some small difference visually similar in the diagram

you can check the wiki article on UML state diagrams for further reading

Answer 5

I love this code!

We have had twenty years of object-orientation now, but some people still don't get it. Hey Geeks: There is a difference between spaghetti carbonara and spaghetti code.

As this is generated code, why don't you visualize it from a higher level of abstraction? We don't know how "generated by another file" works, but it seems that the mechanism is easier to understand from the other files perspective otherwise code generation wouldn't make any sense. Provided that the transformation is correct, the information is the same.

Answer 6

Many options exist to graphically represent state machines, among them:

• state diagrams and its popular successor statechart, which is integrated to UML.
• Petri net, if you want to control combinatorial explosion.

Some tools are able to generate code from them.