Re: UML module hackery

[Barrie Slaymaker <barries slaysys com>]

On Mon, Nov 11, 2002 at 04:03:05PM +1100, Matthew Palmer wrote:
>       * In class diagrams having the terminus of the line in the centre of
>       the object, and then rendering the line only in those points where
>       it isn't inside an object.  Also, any arrows or other symbols would
>       get rendered at the edge of the object.  Toss out tie-points
>       completely.  Yuck.

:).  Everyone has their preferences.  Personally, I'd like to see the outlines
of shapes be connectable anywhere, with snap-to points where they cross the grid
and at the connection points described for the shape.

> * Storing actual code along with class methods.  It's always felt to me that
> UML would make a really nice "graphical programming" tool, if we could store
> program code along with the structural elements.

Let me share some of our experience with this sort of thing.

I write a markup language and processing too called "StateML" to describe state
machines with docs and snippets of inline code that can generate (via code
templates) any source code we need (usually C variants) and (via graphviz)
diagrams.  Now, graphviz is nice and all, but hacking XML and getting servicable
but odd (from a human point of view; I show these to clients) layouts is
not what I want.

It would be far better for my purposes to use tool like dia to build visually
clear diagrams and add in the code annotations (StateML lets you render the
graphs with or without code snippets, descriptions, etc. for the different
audiences).

One thing I've found is that even moderately complex state machines can
benefit from "arc folding": if several events all lead to the same transision
and underlying code, the representing them as a single line with multiple
event / guard condition labels but one action is handy.  Otherwise you get
an magnetic field of almost identical arcs.  This is not uncommon when
building things like lexers and protocol implementations with state machines.

I keep wanting time to dig in to dia and build a state diagram language that
lets me attach these same snippets of code to dia objects and to add comments
to them for generated documentation (ie more verbose than the labels for the
state, so $client_engineer can see what a state really means, not just
its name).

I've gone as far as building some SVG shapes files, but dia needs to grow
a bit before I can use those to define shapes with behaviors like those
implemented in C/C++.  And it would be nice to have unconnected line
ends glow red hot, so that the post processing extraction tool isn't the
first time a user notices that a line looks connected but isn't.

> It also means that we can
> skip out of letting out UML model fall to pieces as soon as we start to
> code, because we'll still be working with it.

This is the biggest advantage to StateML for us: we change the StateML and
the images, docs and code all get regenerated.  The second biggest advantage
is the communications it facilitates: getting a clear, accurate diagram to
other engineers.  Another is that bugs tend to be in the code generator and
are often rampant, so many states have the same bug, so they are easily
found and nailed.

I would recommend a language neutral, template based approach to generating
the code.  The StateML tool I have is in Perl and it uses TT2; with multiple
templates selecting different XML namespaces, I can include code snippets for
multiple languages.  This comes in handy when, say, testing a state machine
with gcc and then deploying it with $funky_12_bit_risc_compiler.

Just some related experience; I'm quite interested in the topic of visual
programming languages, and I've repeatedly tried to get some time in to
growing dia in that direction, but real life intrudes before I get far.

- Barrie