Wilfred Thinking Aloud

Thousand words say more than a single picture

In my spare time, I have begun to work on a solution for yet another itch I have had for years. One of my recent involvements in a greenfield software development project brought it all back again.

I had been working on a framework, and had basically already put some abstractions (Java classes and interfaces) together to guide the discussion, put my head around it, and prototype some of the things I had in mind. In fact, a lot of things were already tested, and everything seemed to be working just fine.

Then people started to ask my for detailed class diagrams. Now, don't get my wrong. I like UML. I like modelling. In fact, I already created a couple of UML diagrams to explain some of the relevant abstractions. But in most of those circumstances, I leave a lot of detail out. I don't list all of the attributes and I don't list any of the methods on the class. So although the UML is precise, it leaves out a lot of the details.

Anyhow, after some evasive manoeuvres, I ended up using a tool to reverse engineer all of my sources into a diagram, knowing that this diagram would be invalidated the moment that people would work on the code. And I have to say, it looked impressive: lots of classes, lots of interfaces, lots of associations, lots of attributes, lots of operations. The only thing that it didn't do is help you to understand how things fitted together.

So here is my problem: what is the point of having class diagrames knowing that they will be invalid as soon as somebody touches the code, and what would minimally need to go into a Java source based class diagram to be helpful at all.

A related question is if pictures really say more than a thousand words, in all circumstances. If you want to express the exact same thing, then you need very complicated pictures to express all of that. The reverse is also true. Simple pictures can easily be explained in less than thousand words.

In reality, in a lot of the situations, just listing the attributes and methods do not add any semantics at all. People may think that it explains something, whereas in reality, it is just interpretation: listing an operation called calculate() could mean anything, ranging from calculating the size of a JFrame to calculating the 10^10 number in pi. In fact - and this may surprise you - it does not even need to involve any calculation at all. The operation calculate() might start 'Super Mario Bross' for all I care.

So, generally speaking, having detailed class diagrams still require a lot of words (possibly thousands) to explain what it means.

Anyhow, I suspect that people will not always agree with my opinions, so in order to prevent me from waisting valuable time to frequently reverse engineer code, I thought I would make my life a little easier, and to create something that would generate class diagrams from my sources automatically, as part of the project build cycle.

I suspect this will take my quite a while, so I will probably blog about this more often. For now, it may be interesting to show some examples of what I am able to do today:

This is just one of the pictures generated from the sources from the piece of software itself. You may notice that it leaves a lot of stuff out. (On purpose.) At this stage, I intend to have it eventually included in my JavaDoc, so I there is one central class for every diagram. For that class, I list all of the attributes and methods. Notice that I am also deliberately leave out the package names for related classes: adding the package names would make it impossible to read. (You would end up with diagrams with more than a thousand words. I hope you see why that would be a problem.)

( Jan 08 2006, 09:01:15 PM CET ) Permalink