Introduction

UMLGraph allows the declarative specification and drawing of UML class and sequence diagrams. The specification is done in text diagrams, that are then transformed into the appropriate graphical representations.

There is no rule specifying that models should appear in a graphical form. A model is a simplification of reality, so a model for a software artifact could really be an outline of that artifact; think of a class definition without code in the method bodies. However, we usually prefer to examine many of our models in a graphical representation: UML employs ten different diagrams for visualizing different perspectives of a system.

Designers typically create their model diagrams using a drawing editor. However, all drawing editors require the tedious placing and manipulation of drawing shapes on the canvas. The effort and the motor coordination skills required for this activity are mostly irrelevant to the end result: unlike architectural or mechanical engineering models the appearance of a software system's model diagram is only marginally related to the quality of the represented software design.

Computer power and automatic graph drawing algorithms have now sufficiently advanced so as to allow the automatic placement of graph nodes on the canvas and the near optimal routing of the respective edges. We can therefore design models using a declarative textual representation and subsequently view, publish, and share them in graphical form. UMLGraph's support for declaratively specifying class and sequence diagrams is part of an ongoing effort aiming to support all ten types of UML diagrams.

Creating models in a declarative, textual notation offers a number of advantages.

First of all, the model composition mechanism matches well both a programmer's high-level skills, the textual abstract formalization of concrete concepts, and the associated low-level skills, the manipulation of text using an editor and other text-based tools.
The declarative notation, by being closer to the program's representation (the notation I experimented with is based on the Java syntax and semantics), forces the designer to distinguish between the model and the respective implementation, between the essential system characteristics and the trivial adornments. It is more difficult for designers to get away, as they often do now, with drawing for a model a nice picture of the implementation they have in mind.
The declarative representation is also highly malleable, the existing visual structure does not hinder drastic changes, nor is effort wasted on the tidy arrangement of graph nodes a psychological barrier against massive design refactoring.
Declarative models are also highly automatable: they can be easily generated from even higher-level descriptions by trivial scripts and tools operating on design process inputs such as database schemas, existing code, or structured requirements documents.
With a declarative specification under the programmer's control a macro processors can be used for configuration management, allowing the same model to be used for generating diverse diagrams.
Revision control and team integration activities can utilize the same proven tools and processes that are currently used for managing source code. Thus with a tool like Subversion or Git one can keep track of design revisions, create and merge branches, monitor model changes, and split work among a team.
Finally, the declarative approach can readily utilize existing text processing tools for tasks that a drawing editor system may not provide.

Consider how your favorite model editor handles the following tasks and how you could handle them using a simple Perl script or a text-processing pipeline applied to the declarative model specification:

identify all classes containing a given field (as a prelude to an aspect-oriented cross-cut);
count the total number of private fields in a given design;
order methods appearing in multiple classes by their degree of commonality;
identify differences between two designs.

All the above tasks can be easily performed in text files using Unix commands such as grep, wc, grep ... | sort ..., and diff.