6 Tips for readable Stateflow charts

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.

Background

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.

levels

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.

#1 Consistency

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.

corrected

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 canc2 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.

levelsLikewise, 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.

#4 Resize!

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

  1. Is the state large enough to hold all the text in the state
    overflow.jpg
  2. 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?)
    bigEnough
  3. Is the state larger than it needs to be?  When states are larger than required they take up valuable screen space.
    toBig

#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.

selfLoop

#6 Temporal logic!

Use of temporal logic, instead of self-defined counters, ensures that the duration intent is clear in the chart.timverVCnt

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.

Final thoughts

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.

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s