On code and diagrams

TextUML is a textual notation for UML. The TextUML Toolkit is an Eclipse-based IDE-like tool for creating UML models using the TextUML notation.

Other tools follow the same approach. Emfatic (now an EMFT subproject) has been doing the same for EMF Ecore for a long time; the TMF project aims to be for textual modeling what GMF is for graphical modeling, and will be based on GMT‘s TCS and xText components.

Still, people are often puzzled when I explain what the TextUML Toolkit is. A common question is: “if I am going to write code (sic), why do I need UML anyway?“.

Dean Wampler from Object Mentor wrote on his blog a while ago a post entitled “Why we write code and don’t just draw diagrams” (which is now gone but still available via archive.org). It is a short post, but he presents very good points on why a graphical notation is usually not suficient and is bound to be less productive than a textual one when it comes to modeling details. For instance, on the saying “a picture is worth a thousand words“, Dean wrote:

What that phrase really means is that we get the ‘gist’ or the ‘gestalt’ of a situation when we look at a picture, but nothing expresses the intricate details like text, the 1000 words. Since computers are literal-minded and don’t ‘do gist’, they require those details spelled out explicitly.

Couldn’t have said it better.

I strongly advise you to read the original post in its entirety, but I will leave you with another pearl from Dean’s post (emphasis is mine):

I came to this realization a few years ago when I worked for a Well Known Company developing UML-based tools for Java developers. The tool’s UI could have been more efficient, but there was no way to beat the speed of typing text.

Enough said.

Email this to someoneShare on FacebookShare on LinkedInShare on Google+Tweet about this on Twitter

4 thoughts on “On code and diagrams

  1. Andreas

    May 14, 2008 at 1:03pm

    Hello Rafael,

    let’s not forget that the UML defines 13 diagram types and TextUML only addresses the class diagram (static structure).
    What about designing and/or documenting complex interactions with sequence diagrams?
    A control flow with activity diagrams?
    A state machine with a state machine diagram?
    A system architecture with a deployment diagram?
    While the static structure of a software system is relatively easy to grasp (anyway, the first thing I do when looking at new code is run Doxygen on it and look at the nice diagrams generated from the code) the dynamic aspects are deeply hidden in code and they can be very hard to discover. A current diagram with the right abstraction level can give you more insight than weeks of reading code.
    In addition, the static structure of the code is usually the “easy part”. The hard part are the dynamics and interactions. So – a bit evil minded – I could say that TextUML only addresses the parts of a software system that cause only a fraction of the overall effort of creating a complex software system.

    Best regards,
    Andreas

  2. rchaves

    May 14, 2008 at 9:46pm

    Hi Andreas,

    Thanks for your comments, glad to hear from you again. You make interesting points, as usual.

    > let’s not forget that the UML defines 13 diagram types
    > and TextUML only addresses the class diagram
    > (static structure).

    True. However, even though I can’t think of a single UML diagram type for which a textual notation could not at least do the job, supporting them all is not the goal of the TextUML Toolkit.

    The goal is to support enough features of UML to enable basic (elaboration-style) model-driven development – described in the post on UML modes as UML as blueprint .

    So, yes, the usefulness of the TextUML Toolkit is limited to what you can do if you restrict yourself to modeling structure only. But many (most?) of the code generation tools in the market have the same limitation, and they are quite useful.

    > What about designing and/or documenting complex
    > interactions with sequence diagrams?
    > A control flow with activity diagrams?
    > A state machine with a state machine diagram?
    > A system architecture with a deployment diagram?

    My interest in UML is primarily as a language for model-driven development. That, for starters, excludes diagrams such as use case, sequence, object and communication/collaboration diagrams. Those basically support the UML mode known as UML as draft.

    And even though some other diagrams can be useful in the context of MDD (deployment and package, for instance), they are not really essential.

    The only diagrams I think are really important in the context of model-driven development are the class, activity and state diagrams. Actually, depending on what/how you are building, you can get by with the first (which is the core diagram in UML) and one of the other two.

    > In addition, the static structure of the code is usually
    > the “easy part”. The hard part are the dynamics and
    > interactions.

    Totally agree!

    > So – a bit evil minded – I could say that
    > TextUML only addresses the parts of a software
    > system that cause only a fraction of the overall effort
    > of creating a complex software system.

    You are right if we take into account what you can see in the TextUML Toolkit. But in a larger product I have been working on for quite a while now (I called it Corcova in the past), which is the sole reason the TextUML Toolkit product exists, you can model activities using (action language-style) TextUML and can do cool things that are only possible if you go beyond the structural aspects (in the spirit of UML as programming language, mentioned in that same post.

    I plan to write in more detail about this sometime this summer, hopefully along with a cool demo! But if you have more questions/comments, I will be glad to exchange more ideas on the subject.

Comments are closed.