Question

I often draw a dataflow on a sheet of paper. Even the planning of my little tools is done on a paper.

There exists UML.
The problem is – I don’t like it. All the tools I’ve used (Visio and a lot of online editors) are just not flexible for my hands. With a pencil you can easily draw shapes and connect them, describe them.

What could you suggest in order to create a diagram of data-flow, sequence diagram, etc. in the fastest, most natural and easiest way except on the computer not the paper 🙂

****Useful links as posted in comments:** SO Link #1 SO Link #2

Right now I am curious about 2 things and one of them was in my minds quite long ago:

1) Mindmap – I’ve tried a while ago, quite liked it but abandoned. Hoever will give it another try

2) Whiteboard. It would be the easiest and most natural method, except that taking a photo and storing it somewhere on a computer would make the process repetitive and boring.

Has anyone other interesting ideas? I would really like to hear what others are using to design their software and the progress of it.

Thanks a lot!

Answer 1

Why do you want to hand-draw the UML at all whether it’s on paper or on the computer?

I agree that you need a model to represent the design. But even in large projects of about 500 man-months, I observed that only 3-4 sequence diagrams really matter and have a chance of surviving the entire lifecycle of the application. Those 3-4 sequence diagrams (and class diagrams that represent their static time relationships), usually represent the high level design of the application.

Or, look at it this way:

Any decent enterprise application will not have 20 different call flows. There will be one or two generic (or abstract) call flows, which all the concrete use cases implement. Let us take a simple Struts / EJB application. The generic flow will be something like – an action class calling a validator and then calling a stateless session bean, which in turn calls a domain class, which will call a DAO. All the use cases of the application just implement this flow with concrete classes that are specific to that use case.

Do you agree?

If you do not, I would like to hear about applications that have 20 different call flows and survived for 5 years after the first release.

If you agree with me, we are boiling down to 3-4 class and sequence diagrams even for large enterprise applications comprising several thousand classes. Why is it a big deal how you draw and maintain those 3-4 diagrams?

You might say that you want to document all the use cases for training or documentation purposes. During my last 14 years of experience in the real enterprise software world, I don’t remember seeing well ‘maintained’ UML documentation. First of all, good documents are difficult to produce and are not found that often. Secondly, they are out of sync with the code most of the time. Most of my experience is with large banks, insurance companies, Auto companies, etc. Those environments are just too hectic and their resources are limited (really? Are we talking banks? Yes, difficult to believe, but true) for ‘maintaining’ good documentation.

So am I suggesting that we get rid of UML?

No. We need visual models to represent complex systems. Human brains seem to be at their best when processing visuals. The visual cortex, which is responsible for processing the visual images, is the largest system in the human brain.

So what is a reasonable solution to easily produce and maintain UML models?

1. Probably we are better off using the current crop of UML tools to draw those 3-4 high-level UML diagrams. If you hate using them, check option 3 below.
2. For the diagrams at the next level of abstraction (any useful models should have different levels of abstraction), generate the UML from source code. You can generate both class and sequence diagrams.
3. In this age of agile methodologies, why not just write the shell classes and generate those 3-4 high-level UML class and sequence diagrams as well? This way there won’t be any UML to maintain at all.

The source code is the truth.

Can you argue against that statement? If not, why not generate the models from the source code itself? I am not suggesting the round-trip engineering, by the way. I am just suggesting a one way trip – from code to models.

There are 2 main problems however with the generated UML.

1. When we hand draw a class diagram, we show the relations between the classes involved in a scenario. Most existing class diagram generating tools allow the user to drop the Java classes (the source code) into the tool and the tool automatically shows the relations between the classes. The problem here is, how does one know about the classes involved in a scenario to begin with?
2. The second problem is the verboseness of the generated diagrams. There are tools available to generate runtime sequence and class diagrams for a scenario. But the diagrams are often very verbose and defeat the purpose of models, whose purpose is to highlight the important aspects and filter out unimportant details.

Good UML generating tools should address both the above problems. There are a few tools in the Java domain that try to address these problems. Check the discussions below:

What tools should I use to visualize structure of my code

Are there any tools for detecting architectural and design patterns in code?

I hope I answered the original question:

Has anyone other interesting ideas? I would really like to hear what others are using to
design their software and the progress of it.

I am the author of the runtime UML generating tool MaintainJ, but I tried to address the original question in an objective manner. Your comments are welcome.