an entry from

Piotr's R&D blog

I recently rescued a very insightful comment by Adrian Buehlmann to my original Morning After entry from the (generally effective, but in this case dreadfully inaccurate) comment spam filter. Adrian takes issue with Reef's fundamental principle of keeping diagrams in sync with code, and argues that Cadifra (the UML editor he's working on) is the right way to go. I think that Reef and Cadifra are complementary, and hope to convince the gentle reader that Adrian and I are mostly in violent agreement.

Let me first pull out some points that Adrian makes that I strongly agree with and that drive Reef's design.

1. The code is the design.

   This is the point that Jack Reeves made back in 1992, and it's just as valid 13 years later.

2. Diagram editors must be very fast and easy to use.

   This is critical, yet most of today's "model-based" diagrams fail the test as you are forced to edit an abstract underlying model "through" the diagram. These tools attempt to enforce strict consistency rules, and require that you cross your T's and dot your I's, severely impeding the workflow. Strictness has its place if the model must be interpreted by a machine, but...

3. Don't generate code from diagrams.

   ...the only reason to have machines interpret diagrams is to make them executable (or transform them into executable forms), and there's no good reason to do that. As Adrian says, if the code is too "dirty" to be the design, clean up your code (or improve the programming language!), don't try to escape the situation by making a higher-level model your primary artifact.

So where do we disagree? Adrian implicitly assumes that UML diagrams should only be used during development, as transient artifacts that augment a developer's working memory and help face-to-face communication. Once the ideas discovered through the diagrams are fixed in code, the diagrams are no longer useful. Given this assumption, synchronizing code with diagrams would be foolish, and all you want is computer-assisted diagram sketching, which Cadifra does very well (check it out!).

I believe, however, that UML diagrams are also useful to convey design information across time and space -- that is, for what is traditionally called documentation. Code by itself is not up to the task, since certain meaningful and important abstractions get lost or scattered beyond recognition when embedded in (current) programming languages. Furthermore, since this documentation will be used by people potentially far removed from the context of the initial development, it is critical that it be consistent with the underlying codebase. (That is, it should augment the design represented by the code and never contradict it.)

One could certainly argue that UML diagrams at this level are not useful documentation, and that the code (with comments) is sufficient. I think there are many indications that this is not true, but rather than argue about it I'm setting up an experiment to see whether some realistic maintenance tasks can be performed better given access to appropriate UML diagrams on top of the code. I'll report on the experiment's results here once it happens -- for now, we're still struggling with the ethics approval process.

In summary, I think Cadifra and Reef fill complementary niches in the UML tool pantheon. Cadifra is great for design sketching and discussion support, while Reef will prove invaluable for maintaining UML documentation for the long run. I think there's even potential for some synergy between the tools, but I'll address that some other day...