State Machine Diagrams – How to Diagram State Machine Code

I'm looking for a way to clearly diagram how multiple applications communicate via a service bus.

That would be awesome. Unfortunately, I don't think it is possible for configurations of any complexity. A sequence diagram for simple scenarios is probably as good as anything else.

Components on a bus both publish and subscribe to messages. Some of the messages may be causally related, forming a protocol. It it difficult to show this graphically, especially the causal relations, when there is more than one protocol in play on the bus.

Electrical bus diagrams have been around for a long time

but they deal with a quantity of a uniform commodity (electrical power) not discrete signals.

I like to show messages sent (on the right) and received (on the left) by each component (and the subchannel/topic structure, if applicable), but again for anything but the simplest of scenarios the diagrams quickly become cluttered and nearly useless.

So let's go back to a more fundamental question: what is the purpose of the diagram? What are you trying to show?

If you are trying to show causal relations between components and messages, then diagramming one protocol at a time using a sequence diagram (or equivalent) should be fine.

If you just want to show the protocols for reference, then putting messages sent and received by each component should be sufficient documentation, but causal/temporal relationships are lost.

Good luck, and please let us know if you find or invent anything better!

I think what you're looking for here is a Sequence Diagram. These allow you to visualize the order in which various modules call eachother via the use of arrows.

Constructing one is simple:

1. Draw your starting class with a dotted line below it.
2. Draw the next class/method in the call trace with a dotted line below that
3. Connect the lines with an arrow, vertically positioned below the last arrow you drew
4. Repeat steps 2-3 for all calls in your trace

Example

Let's assume we have the following code we want to create a sequence diagram for:

def long_division(quotient, divisor):
    solution = ""
    remainder = quotient
    working = ""
    while len(remainder) > 0:
        working += remainder[0]
        remainder = remainder[1:]
        multiplier = find_largest_fit(working, divisor)
        solution += multiplier
        working = calculate_remainder(working, multiplier, divisor)
    print solution


def calculate_remainder(working, multiplier, divisor):
    cur_len = len(working)
    int_rem = int(working) - (int(multiplier) * int (divisor))
    return "%*d" % (cur_len, int_rem)


def find_largest_fit(quotient, divisor):
    if int(divisor) == 0:
        return "0"
    i = 0
    while i <= 10:
        if (int(divisor) * i) > int(quotient):
            return str(i - 1)
        else:
            i += 1


if __name__ == "__main__":
    long_division("645", "5")

The first thing we'll draw is the entry point (main) connecting to the method long_division. Note that this creates a box in long_division, signifying the scope of the method call. For this simple example, the box will be the entire height of our sequence diagram due to the fact that this is the only thing run.

Now we call find_largest_fit to find the largest multiple that fits within our working number, and returns it to us. We draw a line from long_division to find_largest_fit with another box to signify scope for the function call. Note how the box ends when the multiplier is returned; this is the end of that functions scope!

Repeat a few times for a larger number and your chart should look something like this:

Notes

You can choose whether you want to label the calls with the variable names passed, or their values if you only want to document one specific case. You can also show recursion with a function calling itself.

Additionally, you can show users in here and prompt them and show their input into the system easily enough. It's a fairly flexible system that I think you'll find rather useful!