Should I use UML when designing new code and algorithms?

Question

I'm designing a new system and finding that I am struggling with the structure of what I want to do. A symptom is that every time I re-approach the problem I have to try to draw the relationships of the components on paper. (It is not yet clear in my mind as to what these components are precisely or what the relationship is - for example I managed to delete one that wasn't doing anything).

Is UML a useful way forward? I used to be very sceptical and tried early versions where the production version cost way too much money. Now I see there is a plugin in Netbeans which inter alia has a good selection of Patterns (this alone might make it worth the while).

I've read most of the top-level posts on SO and there doesn't seem to be a very clear consensus. My context is that this is related to research rather than coding for a client so the main purpose is not to document a final product but to help clear my mind (and possibly write some simple structures).

If any answers support UML it would be useful to suggest how long it will take to get productive and how often it will be used. (As a reference I use tests, loggers, and debuggers every day).

SUPPLEMENTARY Is there anything in UML software that enforces consistency (at any level) between the code and the diagram. I assume that when, say, a StrategyPattern, is created then it can generate stub code. But can that code be included in such a way that if the Pattern is broken the UML tool detects this?

Answer 1

I can see two approaches to using UML: formally capturing a design, and informally sketching out some aspects of a design as an aid to the design process.

The former is especaially useful on large projects with teams of designers. It requires some discipline and time, but I think much preferable to an alternative of capturing the information in text - the model ensure consistency. If done completely you can even generate code from the model. This appraoch does work, but clearly requires quite a startup effort.

The latter, can be much more informal. May even capturing just the tricky parts of a design, perhaps just for a single developer's benefit, also seems to work. I have done this quite often. I find "playing" with class diagrams really helps to clarify responsibilities. And where I just want to document classes and atributes it saves time. Some tools that offer UML as an alternative view of classes in real code are very nice.

Getting to a stage of drawing class diagrams in a reasonable tool should be a learning task of hours or very few days - assuming familiarity with Object concepts. Learning Object design is a whole different problem.

Answer 2

If you find the extra information that UML has notation for useful - aggregation/composition, stereotypes on associations etc, then use it rather than whatever you're currently using.

I haven't found a tool that's as good as pencil and paper for early design; drawing UML sketches on paper is still using UML.

---

SUPPLEMENTARY Is there anything in UML software that enforces consistency (at any level) between the code and the diagram. I assume that when, say, a StrategyPattern, is created then it can generate stub code. But can that code be included in such a way that if the Pattern is broken the UML tool detects this?

There are plenty of different UML tools, and some have varying degrees of constraint checking. Normally this is limited to UML syntax, but there is also object constraint language which can be used to make assertions about the UML model, and some tools can generate code to test these assertions at runtime. ( Here things get a bit hazy, as I've never worked in a shop which has been willing to pay for said tools, as they aren't cheap, and are more commonly used in embedded systems, where most of my work has been technical computing. ) So if you have purchased a high-end UML tool which supports mapping OCL to code generation, set up a stereotype in your tool to express what the strategy pattern is, and then generate code which includes those assertions ( if they are runtime ) or applies the assertions to the structure in the model ( if they are meta model assertions ). ( I'm not quite sure whether the tools let you write constraints against the metamodel - ie assert that a strategy must provide a function which rather than just asserting the pre and post conditions, but then such assertions are also checked by the type system of most languages if you make the method abstract in the super type of the strategy anyway ) . If you then were to reverse engineer your code and it breaks the constraints, it would be flagged by the tool. The problem is that what constitutes an example of some patterns depends somewhat on the intent of the developer rather than anything that can be asserted about the structure created.

Answer 3

use a pencil and paper

Answer 4

In my opinion UML could be very useful for working in big projects in a big team. By using UML you can create a very good architecture by "thinking before coding".

Later you can take the diagrams to consider, if you have everything done as you wanted to do.

Nonetheless, it would be nice to know how big your project actually is in order to give you a good answer?

Answer 5

UML serves as a common language between different ppl in order for all to describe the same domain.

For code and algorithm design, pencil and paper is always the best way, as Omu said.

Answer 6

UML is not going to make your code any better, but can improve you vision about what you are doing.

It is not about whether UML is useful or not for writing code, but about UML's REAL purpose, to enable you to picture what you want to do, what the system looks like.

You need a metaphor, a story to communicate your work. Developers who join the project later on will need this to better understand your code, to have the right context when looking at the details and to ultimately not break stuff.

Don't let yourself be fooled by tools. UML is not a solution per se, it is just one formalized way to tackle a common problem: writing sound systems.

Answer 7

It seems to me that you are saying UML but are really talking about some Code Generation from UML. These are two extremely different things.

UML is extremely helpful, because it is a defacto standard, so if you are drawing two rectangles with an arrow with a triangular point between them. Almost every developer knows you are talking about inheritance.

UML Tools are a different story: Some are cheap and useful: Paper, pencil and eraser for example.

The Tools used for generating code from UML diagrams (or UML Models to be more precise) are sometime expensive, and (IMHO) always useless. The problem is, that the interesting part of the code needs all the little details, and it is extremely slow to enter all these details in a graphical model. A text editor is more useful for this kind of stuff. And even for the easy stuff, like attributes and references it forces an extremely strict usage of UML on you which is just painful. Imagine an english teacher interupting you every time you don't use perfect oxford english.

The kind of tool that I find usefull are the ones that allow you to draw UML diagrams in free way (Enterprise Architect, Visio, Whiteboard) and the ones that create UML diagrams from your code. Like this plugin for IDEA http://plugins.intellij.net/plugin/?id=3202 (It was done by a coworker of mine so I am biased)

Answer 8

Personally, I think you're approaching this problem from the wrong start point. You

[are] struggling with the structure of what I want to do. A symptom is that...It is not yet clear in my mind as to what these components are precisely or what the relationship is - for example I managed to delete one that wasn't doing anything.

If you're struggling to understand what the system your designing does, should do, or how it works then this suggests that you've started, or are about to start, without a clear spec. It might sound trite, but if you don't iron out the misunderstandings before you start coding, you'll likely create for yourself a hell of a mess when the system's built and needs to have features, or processes, or relationships, or interactions added in or removed because it doesn't do what the client wants.

First produce a clear write-up of what you think the client wants. Give that to the client, at which point s/he'll (probably) do, or say, something unflattering and point out the stuff you missed. Or didn't think was important. And ask why the software does 'x,' 'i,' and 'r' when he wanted 'a,' 'b,'c' and 'x.'

It's also typical at that point for the client to remember super-feature 'M' that he can't live without.

Specs save you time and effort. Even before pencil and paper UML or flowcharts.

Just to back up some of what I've said: Painless Functional Specifications, by Joel Spolsky. Read through, it is convincing.

Answer 9

Martin Fowler is IMHO right when he says there are three ways to use UML:

• as a sketch of what you are going to do
• as a blueprint for what you are going to do
• as the thing you are going to do in itself

It sounds like you are mostly leaning towards the first, with a side order of the second. It definitely helps to pick one and set your expectations correspondingly - you can't expect to execute a sketch, or produce an executable blueprint in 3 minutes.

Whether it works for you depends on a bunch of things like:

• how visual you are as a thinker: people vary very strongly in this.
• whether you can get an effective tool for free, or from your budget.
• whether you need to communicate the design to other people
• if you are effectively using some other means of design (e.g. test driven design).

Answer 10

Personally, I steer clear of code generation or round-tripping for the reasons already mentioned (e.g., an editor is more natural for the details). I just find it easier to look at the model and write the code. The only time that I have used this was with ObjectDomain and I think that half of the reason that I used it was to play with Jython since their code generation is based on writing extension classes to walk the model and generate classes.

Generating a model from code is useful if you are trying to figure out how a code base is structured. This is generally useful for Java-based projects since UML is a pretty natural fit for OO languages with introspection - C++ is a different story altogether. The quality of the UML environment makes a difference here but so does the code base itself. I know that the representation of C++ templates is something that very few modeling environments get right. I would expect that Java generics would present a similar problem.

I use UML for few different purposes:

1. thinking through a design or architecture
2. describing an architecture or tricky design detail to colleagues
3. generating diagrams to support a document

The interesting thing is that I use different tools for each of these. I've gone through a number of modelers (in rough chronological order): Objecteering, ObjectDomain, Visio, ArgoUML, Poseidon for UML, and MagicDraw. I use Visio and MagicDraw for most purposes.

When I am in the design phase and thinking through a system architecture or more detailed design, I use UML as a formal tool so I use a true modeler - MagicDraw. I find that constructing a UML model is a good way to capture my thoughts. A side effect of using a real modeler here is that it forces me to think about methods and structure and not just flow. When I am struggling with getting a design right, I force myself to use UML in the most formal sense. Make sure to model everything precisely - for example: asynchronous operations are best modeled as signals and receptions. I struggled with this for a long time. The key here was to understand formal UML and how my chosen modeling tool represented each concept. This is probably the most important take away from this long rant.

When I am using UML as an ad hoc communication tool, trying to describe something to a colleague for example, the most effective tool is really a whiteboard and markers. I find that formal UML isn't that useful here - just the basic structural diagram and sequence diagram stuff. Surprisingly enough a number of these have been saved by camera phone and mailed around to describe various concepts... go figure.

Embedding UML diagrams in documents usually involves Visio though I never use the official UML modeling support. Use Pavel Hruby's stencil instead. The UML model mode of Visio is broken in so many ways that it really isn't worth the money or effort. However, with Pavel's stencil, do ad hoc UML diagrams is quick and easy. The other piece of advice here is to use a vector graphics format instead of a raster format for the images themselves. My company, like many others, is infected by the Microsoft Office virus so I am pretty much stuck with Word for documents. In this case, I use Enhanced Metafiles (*.emf) as my image format of choice. If you are working in a DocBook environment, then use SVG instead.