On the heels of a popular “5 tips for readable Simulink models” I am following up with a companion post. While much of this material can be found in the “Stateflow best practices” document found in this sites reference section these are the 5 I find most critical.
First a few background concepts. The concepts of “levels” in a Stateflow Chart is a measure of how many states exist within a state. The count starts at the highest level state and increments for each substate.
Stateflow includes the model construct of a “Subchart.” Like subsystems in Simulink, subcharts encapsulate all the states and transitions in the state into a single “masked state.”
When counting levels a subcharted state counts as one state regardless of how many states exist within the subchart.
There are two main aspects to consistency in Stateflow charts decomposition of transition information and placement of transition information.
Transition information consists of both the transition condition (or event) and the action.
The image above shows 4 methods for decomposing the transition condition and action. In general, I recommend a separate transition for the condition and the action. This is for two reasons. First, for complex conditions, the length of the text can make it difficult to read; adding in additional text in the form of the action just aggravates this issue. Second, by placing the action on a second line it is possible for multiple transitions to use the same action.
A slight modification to the previous image can show the importance of constant placement. If the placement of information is inconsistent, e.g. in some cases above and some below, left or right, it becomes difficult to associate the transition information with a given transition.
#2 Maximum states per level & maximum levels per chart
For any given State I recommend a maximum of 3 levels of depth; if more than 3 levels are required consider creating a subchart for the part of the state requiring greater depth.
Likewise, I recommend an absolute maximum depth of 5 states. The first recommendation promotes readability at any given level within the chart. The second recommendation promotes understanding of the chart as a whole.
#3 Number of States
As a general rule of thumb, I limit the number of states that I have on any given level to between 30 and 50. When I find the number of states at a level exceeding that value I repartition the chart using subcharts.
Even more than in Simulink, resizing states can dramatically improve the readability of the chart. There are 3 things to consider in the size of the state
- Is the state large enough to hold all the text in the state
- Is the state large enough to have all of the transitions reasonably spaced out (e.g. will the text on the ouput transitions be readable?)
- Is the state larger than it needs to be? When states are larger than required they take up valuable screen space.
#5 Stright lines, please
In the majority of cases the use of straight lines, with junctions to help with routing, provide the clearest diagram appearance. The exception to this recommendation is for “self-loop back” transitions such as resets.
#6 Temporal logic!
Use of temporal logic, instead of self-defined counters, ensures that the duration intent is clear in the chart.
In this example, if the time step is equal to 0.01 seconds then the two transitions result in the same action (transitioning after 1 second). However if the time step is something other than 0.01 seconds the evaluation would be different. Because of this when the intention is to transition after a set time temporal logic is always preferable.
Again these are just a few tips on how to make your Stateflow charts more readable. I would, as always, be happy to hear your suggestions.