The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

How to document "flow" in event based scripting language?

I am the maintainer of a complex module in our application. It's written in Cincom Socrates. The language itself is a (event based) scripting language much like VBScript with methods and functions. On top of that (or besides) there is "trees" in which methods can be chained together in a sort of graphical flow diagram.

So a piece of code can be executed by:

1) An event (eg. a click on a button)
2) A call from another piece of code (method)
3) A tree

Combinations are allowed, eg. a click on a button can run a tree with a method that calls other methods. Methods are not "locked" to their type of execution, so method "doStuff" can be called by tree "initialize" and afterwards sit and wait for the user to click on a button.

Over the years several developers have been in touch/responsible for the module and it's scope has been expanded as well, so it's doing things it wasn't designed for in the first place. Lot's of workarounds and quick fixes, but basically all developers has had very good intentions and there is very few (known) bugs.

To sum things up: It's very difficult to get an overview of the code. I'm dreaming of a tool that reads all the code and print out a huge multi-dimensional poster with boxes and arrows that I can put on my wall :-)

But what's the next best thing? How do you document these types of application? Do you know of any good examples out there?
TheGrumpyFamilyGuy Send private email
Wednesday, August 15, 2007
IanH. Send private email
Wednesday, August 15, 2007
document the event-driven aspects with a state diagram and the procedural aspects with (ugh) a flow chart (or whatever the current flow-chart replacement du-jour is).
Jeffrey Dutky Send private email
Wednesday, August 15, 2007
UML state transition diagram

Monday, August 20, 2007
Use a data-flow-diagram.  However, your 'top level' will have to be a new 'event-generator' module, which triggers each of the 'events' the system will support.

This will be a 'stand-in' module for all the different ways an 'event' can really be triggered.  It provides an organizing principle for the DFD tree.

Sadly, DFD drawing programs are out of style now (and were horrendously expensive when they were in style).  But it summarizes complexity very nicely.

Personally, I use Understand for C++, and Understand for Java, to draw call-diagrams and code walk-throughs when I have these problems.

Visio will draw very nice DFD's, but not automatically from code analysis.  Sad.
Monday, August 20, 2007
Thanks for the suggestions. It seems that there really isn't a 'silver bullet' for this ...

I played out with the Graphviz 'dot' program and it might be the way we go. We 'just' need to add some comments in our source code files, which tells 'dot' which dots, shapes and connectors to draw. That process might be of more value than the final drawing... ;)
TheGrumpyFamilyGuy Send private email
Tuesday, August 21, 2007

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz