The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

reading UML

I have trouble reading UML. It just isn't obvious to me what it is trying to say when I glance at it. Granted, I don't use it often (which is probably part of the problem) and whenever I need to look up something in my favorite design pattern book, I also have to reach for a UML book to decipher the diagrams (mostly class design stuff).

The thing is that I am a visual learner (I think most people are) and I would really like to use UML more often. However, there is some kind of impedance mismatch somewhere.

Is this your opinion as well or is it just me?  :D
UML_is_not_obvious
Thursday, June 05, 2008
 
 
>I have trouble reading UML
You aren't alone!

It's fine for the simplest sort of thing that can be drawn on a whiteboard, but as soon as it gets complex enough to be useful then it's simpler to read the code.
Add in the rediculous cost of the tools and you can see why "flowcharting for the 90s"never really caught on.
Martin Send private email
Thursday, June 05, 2008
 
 
UML is a conglomeration of three different guys drafting approaches -- Booch, Rumbaugh, and Jacobsen.

The most useful diagram is the "Class Diagram" -- and this basically describes how the code is "packaged".  The "Sequence Diagram" explains how the code "runs" -- but having left out "creation" and "destruction", as well as "return values", can be vague.

Bottom line -- UML was designed to be a "Design Language", of sufficiently high level that "Something Wonderful" had to happen between the UML and the actual code, it wasn't going to be mechanical.

In recent years, they've tried to ADD stuff to UML so it WILL "transform" into code -- Model Driven Development is based on this, I believe.  But I think UML is basically un-suited to this purpose.  It's too big, too unwieldy, it hides some of the critical details (like constructor and destructor) and gets cluttered with other details which aren't important.

Basically, UML isn't "complete" by itself, it's meant to be a framework to hang LOTS of textual description on.  And being the product of three men, it's WAY too complex and cluttered.  I agree with the problems you're having with it.
AllanL5
Thursday, June 05, 2008
 
 
+1 for AllanL5

UML seems to be a high-level way to communicate between the programmer and the business person. If I try to create a UML diagram detailed enough to generate code, it becomes difficult to understand.
hobit Send private email
Thursday, June 05, 2008
 
 
When your UML diagram exceeds the size of the napkin your problem has exceeded the domain of UML.
Mr. Lucky
Friday, June 06, 2008
 
 
UML has many deficiencies but you can certainly show constructors, destructors and return messages on sequence diagrams.
John Topley Send private email
Friday, June 06, 2008
 
 
It really depends on your target audience as well (i.e. Don't include a lot of intricate details about return values and constructors if you're going to give the diagram to marketing).  When I've used UML in the past I've only ever made it as complicated to get my point across to my target audience and it has seemed to work out pretty well.

As far as learning UML, Google it for tutorials and go from there.  There has got to be at least a decent tutorial on the web somewhere.  If you're of a book person, I would checkout "UML Distilled Third Edition" by Martin Fowler.
Brian Shipe Send private email
Friday, June 06, 2008
 
 
When I am trying to understand new code, I always find myself taking pictorial notes that look similar to UML. At that point, I inevitable ask "why not use UML then?", but it just doesn't seem to work.

My hypothesis is that there is two sides to studying code. There is the static class relationship stuff, and then there is the run-time dynamic stuff. The Sequence diagrams are ok for dynamic behavior, but they get unwieldy pretty quickly.

To me, UML appears to be more of an academic exercise. It is not natural or practical, possibly because I am not very fluent in it; or perhaps it's the way the associations are depicted using arrows and such as if there is "flow", but not really... Maybe UML was not quite designed for what I am trying to do.
UML_is_not_obvious
Friday, June 06, 2008
 
 
I've used Enterpise Architect from Sparx (for example), to:

* Declare all classes (by which I mean, to declare the name of every class, the signature of every method including constructors and including each method's return code, and the projects/namespaces in which each class is contained)

* 'Forward engineer' the class declarations to source code

* Use a standard source code editor (Visual Studio) to define the classes' method implementations, and the classes' member data

* In the UML model, intelligently arrange class declarations into class diagrams:

  - Don't try to show all classes on one diagram

  - Add appropriate decriptive notes

  - Use diagram options to hide inappropriate details as necessary, e.g. private methods, helper classes, etc.

* 'Reverse engineer' from source code back to the UML model: so 'round-trip engineering' worked as expected

* Hyperlink the class diagrams to other diagrams, e.g. Use case diagrams and deployment diagrams.

I think it worked well: so I'd recommend it, if your product or your process requires that detailed a level of design diagram, and/or of traceability from Requirements and of Use cases through to Design (and Deployment).

Sequence diagrams, however:

* I find that sequence diagrams are very useful in the functional specification of network protocols: the sequence of messages between components.

* I've found them far less useful though for illustrating the sequence of methods which are invoked by a transaction within a software component:

  - By the time a transaction involves a chain of more than about 5 classes, the sequence diagram is too wide to be readable

  - Adding the signatures (of the method being invoked) to the diagram makes the diagram even wider

  - Other reasons too.
Christopher Wells Send private email
Friday, June 06, 2008
 
 
The problem is that if you just use it for napkin level views then just draw boxes and arrows.
If you try and document the entire system you end up designing the software around the constraints of the UML.

If you are making design decisions based on the number of boxes that your favorite UML tool will fit on a single sheet of paper you are probably not going to end up with the perfect design.
Martin Send private email
Friday, June 06, 2008
 
 
> I think it worked well: so I'd recommend it, if your
> product or your process requires that detailed a level of
> design diagram, and/or of traceability from Requirements
> and of Use cases through to Design (and Deployment).

I am more interested in reverse-engineering, reading, understanding code rather than designing it or any other formal "development" process.

Pen&paper, code navigation tools and documentation all help with this process, but I thought more could be extracted from the code by mapping it to a UML-like visual representation. Couldn't find any such tools though.
UML_is_not_obvious
Friday, June 06, 2008
 
 
You can easily reverse-engineer class declarations.

Worst case is that this gves you a single (much too large) class diagram, with the classes (and their details), sorted at random and/or alphabetically.

Doing an auto-layout of this diagram will group together related classes: classes which contain other classes (by reference or by value), and classes which subclass base classes and/or which implement abstract interfaces.

The class diagram is a static representation: it illustrates the layout of class instances in RAM.

The class diagram is not a dynamic representation: it doesn't necessarily show how classes colaborate (invoke each other's methods) to implement transactions; you can try to infer this by knowing that you can invoke another class' methods if and only if you hold a reference to an instance of that class, however a class diagram doesn't illustrate invoking methods on an instance which a method has received as one of its parameters).

One of the dynamic representations of software is a sequence diagram. You may be able to run the software with a debugger, and have the tool use the debugger to auto-generate a sequence diagram which traces the flow of execution of a thread ... this lets you reverse-engineer sequence diagrams ... sequence diagrams, auto-generated or otherwise, are still problematic to read though for reasons I mentioned above (e.g. they're too wide).
Christopher Wells Send private email
Friday, June 06, 2008
 
 
@Christopher Wells:

You basically captured the essence of what I do by hand. Is there such a tool that will do this automatically or close to it? If not, would it be worth building one?
UML_is_not_obvious
Friday, June 06, 2008
 
 
If by "it" you mean reverse-engineer to class diagrams, and/or auto-generate sequence diagrams from a debugger, thn you might try evaluating Sparx's Enterprise Architect( and/or other UML tools which can "reverse-engineer" from source code).

I don't personally use UML only to reverse-engineer, read, and understand code. Alternatively, I've seen some people in the past (1990s) recommend http://www.scitools.com//products.php ... I found though that a huge machine-generated picture of the code is no easier tho understand than the huge code-base itself ... presumably other people with different needs found it more useful than I did.

As for whether it's worth building one: this is probably a question of, "If you have to ask, then the answer is 'no'".

Don't let me stop you from succeeding, though! Because <big>if</big> you can develop something that's better than existing tools for explaining software to programmers, then our demand for such a tool (or clones of it) might be immense.
Christopher Wells Send private email
Friday, June 06, 2008
 
 
I agree that UML is useful for high-level aspects of design. Specifying details like each and every method signature or each and every member is best reserved for actual implementation and can hurt readability.
MoffDub Send private email
Wednesday, June 11, 2008
 
 
Last semester, I took my degree's project course.  I had to use UML.

While some bits of UML are useful, often, I find the text versions to be clearer.

Sequence diagrams are, I think, particularly time-consuming and useless.  I think that writing use cases in a form where the entities are specifically identified (no pronouns and such) would work much better.

Here is something for the entrepreneurs.  I have noted that many of these sorts of tools are very awkward to use.  Their UIs are horrible.

Sincerely,

Gene Wirchenko
Gene Wirchenko Send private email
Wednesday, June 11, 2008
 
 
My take on the UML is that it is meant for communication, not specification.

The trick about creating clear UML diagrams is to choose a specific focus for it (i.e. what you're trying to convey) and then decide what to leave OUT.

A diagram is simply a view onto a model, leaving out many details. I.e it is not the model itself.

A diagram in isolation is seldom useful, it really needs a context in which it is used to illustrate or support an explanation. For example, there's no such thing as THE class diagram of the system.

If you find them difficult to read, the ones you've seen were probably not focused well. Or perhaps you need to become more proficient in the notation.

If used well, I find they can be very informative and make it much easier to understand a design/domain.

Since I'm deep into sequence diagrams right now, I'll respond to some of the inaccurate statements made about them in this thread.

--

>> The "Sequence Diagram" explains how the code "runs" -- but having left out "creation" and "destruction", as well as "return values", can be vague.

This is simply not true.

>> By the time a transaction involves a chain of more than about 5 classes, the sequence diagram is too wide to be readable

Find yourself a better tool. You should probably also stick to depicting specific concrete scenarios.

>> Adding the signatures (of the method being invoked) to the diagram makes the diagram even wider

SD's aren't meant to show signatures, those are documented elsewhere.

>> The class diagram is a static representation: it illustrates the layout of class instances in RAM.

Class diagrams show classes, not class instances and RAM has nothing to do with it. Perhaps you were thinking of object diagrams?

>> Sequence diagrams are, I think, particularly time-consuming and useless.  I think that writing use cases in a form where the entities are specifically identified (no pronouns and such) would work much better.

Find yourself a better tool.

--

The reason why generated diagrams are usually so awful, is because they lack focus. To create a diagram from a model or code, you really need an intelligent 'agent' to provide focus and decide what to show and what to leave out.

Note that this 'agent' does not necessarily need to create them by hand! One could do this through declaratively and then let a tool create the diagram.

If any of you are doing java and want to give this a try on your own code over the summer, contact me.
Yanic Inghelbrecht Send private email
Sunday, June 15, 2008
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz