Original URL: http://www.theregister.co.uk/2007/08/16/verity_stob_software_diagramming/

In the beginning, there was the flowchart...

Software diagramming - a warning from history

By Verity Stob

Posted in Verity Stob, 16th August 2007 12:45 GMT

Stob

Those who can, do. Those who can't, make those who can draw a picture

My first effort in instructing computers, about 30 years ago, was drawing a flowchart. Here it is as I remember it, albeit without the smears and crossings-out with which my 14-year-old self doubtless decorated the original.

A simple flowchart describing filling a bathWe were unconstrained, in those far off days, by such piffling issues as web interface, unit tests, or code efficiency. Nor did we have to contend, as did some of my luckier contemporaries, with complex systems where punched cards were sent off to a local bureau.

The fact was we simply had no hardware at all, unless you counted the clear plastic stencil that had to be bought from WH Smith's. The only opportunity we got to exercise our "code" was by slogging through a "dry run", a notably unsatisfactory exercise involving an imaginary computer. It was, to borrow a crisp, vulgar phrase from Robert Robinson, "...like losing one's virginity without having the f*ck".

When a school micro finally did arrive, a year or two later, those of us who had been bitten by the programming bug gleefully threw our inky stencils aside and proved we could tackle non-Radox problems without diagramatic props.

But after that uninspiring formative experience, I have tended to be suspicious of those who would oblige me to make pretty pictures when I should be banging out code. This article is a record of how those suspicions have panned out.

Again with the flowchart

Flowchart worship persisted long beyond the point where even British management might have been expected to spot they were rubbish. In the mid-1980s, I watched from a safe distance as a colleague attempted to code up an entire application from a flowchart specification. This massive document, beautifully hand-Rotringed on best engineering paper, was hundreds of pages long. Its pages all looked something like this:

A flowchart with very many connection lines and very little else

Only much bigger and scarier. Any sense of structure of the original program had, naturally, been entirely suppressed.

My colleague operated a dual coping strategy to deal with this monster: during working hours she wept delicately and persistently; during the lunch break she scanned the job ads. I don't believe the port was ever completed.

During the late 1980s, the flowchart was at last jeered out of software development. A host of alternatives competed to occupy its throne, usually proprietary and usually associated with an expensive CASE tool. Although some approaches really hit the spot - for example relational database schema design - a lot of other diagramming techniques just left you with the sensation of being lectured at.

For example, there was something called the context data flow diagram. The version I was taught comprised a single circle, surrounded by labelled arrows. A hypothetical clearing bank system would look like this:

A context diagram for a clearing bank, showing 'your money' as input and nothing nice as output

Other not-terribly-good diagrams I was obliged to draw at around the same time were structure charts (I think these were just function call hierarchies); thread diagrams (dull short stories expressed as data flows) and, a little later, class hierarchies.

These last I believe were a hangover from Smalltalk, and when first introduced (always as an IDE feature called a "class browser") were thought to be a vital prerequisite to any OO development. It took a while before it was noticed that nobody used them. This realisation may have coincided with Borland releasing a version of its C++ framework called "OWL". Previous class libraries had displayed as elegant inverted "V" shapes. But this particular version of OWL, the first to make extensive use of multiple inheritance, looked like a basket of wool that had been romped in by an exceptionally lively litter of kittens.

It was enough to put you off your templates.

State of the art

From the foregoing, you may have formed the impression that I am against all diagrams. Not so. The moment is overdue for a mention for the queen of all software diagrams: the state transition.

Out of all the techniques I have described, only the state transition diagram really delivers. It alone can show compressed ideas that would otherwise be hard to express, and it is one of the few diagrams one can draw to design the program, rather than put together retrospectively to document a design one has conceived in another form.

Enough abstract discussion. As a concrete example, here is a state transition diagram I drew a few years ago, portraying the automatic call handling system of a customer care centre:

A large state transition diagram, implying that customer care centres never pick up the phone

I feel sure you agree that this diagram is a paragon of terse clarity.

In fact, equipped with the above, one has all the information needed to design the system's classes. An excellent opportunity to segue into another kind of diagram: the UML class diagram. To keep up the standards of good practice you expect from me, I will (of course) use the Gang of Four's famous State pattern to create my design. Here we go:

An animation of a UML diagram, suggesting that the classes are drawn too close together and are wriggling for more room

Those of you who are watching carefully will notice a slight drop in clarity of intention and available information between the state transition diagram and the class diagram derived from it.

To be fair - and with considerable reluctance - I admit that this is not really the fault of the UMLerites. It is an unhappy consequence of the way the State pattern works that the underlying design is buried in a blizzard of silly little classes. This difficulty is reflected in the production code.

Public Service Announcement: fellow programmers who experience this genuine problem in real life, and who code in C, C++, C#, Java or one of seven other languages, should urgently haul their sorry browsers down to smc.sourceforge.net and pull down a copy of Charles Rapp's splendid State Machine Compiler. This elegant utility, easily bodged into the build, allows you to work directly from your state transition design, without bothering your pretty head with the implementation of the State pattern. Once you have tried it, I promise you will never hand-code State again.

Now let us continue, while we bring the flowchart into the modern era...

OMG it's UML

At about the same time that van drivers were rebadged "logistics operators", a sinister organisation calling itself Object Management Group began a campaign to annexe all known software diagrams, rebadging them "UML". Initially, they confined themselves to invading class diagrams, like the one I showed above. But soon they began poking in their oar elsewhere.

Nor were they above reintroducing old enemies to the field of conflict. Take a peek at a UML activity diagram, representing a typical business software analysis scenario: a concert performance of Beethoven's fifth symphony as broadcast on Radio 3.

A UML Activity diagram, portraying the interaction between conductor, audience and orchestra during a performance of Beethoven's fifth symphony

In the words of Rolf Harris CBE, can you tell what it is yet?

That's right, kids, it's nothing but a multi-threaded flowchart, now with added "swimming lanes" to support multicore processors and increase its natural coefficient of bafflement. This sort of thing is emphatically to be discouraged, and I will be passing among you with my anti-activity petition after this lecture.

However, this is not the silliest kind of UML diagram. Let us end with one of the most modern of UML efforts, to which this honour must surely belong: the Use Case diagram, and its astonishingly feeble stick men.

Here is a Use Case taken from Facebook's "Poke" facility. To respect the privacy of the poking participants, and because this application by design emits near-Frankie Howard levels of innuendo, both poker and pokee are played by actors.

A simple use case diagram

I have, however, found a better use for the elaborate drawing software that generates these things. Inspired by the very splendid xkcd webstrip, it is possible to while away the hours of, um, less productive days producing artwork. Just make sure you don't accidentally slip one into your FDS. ®

Four frame cartoon strip made using Use Case 'actors'