Possible Duplicate:
How often do you use Formal UML?

I'm currently following a study UML called UML Fundamentals.

While studying, I wondered if companies even bother creating system documentation in UML because the companies I've visited as an intern didn't seem to bother with a class diagram. They just went straight down to business, creating classes as they went and adding removing methods/properties because they didn't plan ahead.

Is it worth it to create system documentation like a class diagram?

Is it more costly financially to create system design documents before coding, or just design as you go?

  • Similar, but I'm going to go with not a duplicate. This is explicitly asking about cost/effort of creating diagrams and if this cost/effort is worth it. – Thomas Owens Jun 5 '11 at 13:09
  • Interesting question. I'm interested in the answers. Though, where I work we don't tend to do any diagrams. I'm hoping to help start doing them, though :] – Jon Jun 5 '11 at 13:21
  • I can't answer your "is it worth it?" question, but I can tell you that in sixteen years of working as a developer, on various platforms across various industries, I've never seen anyone create a UML diagram, nor even heard a rumour that anyone might have done so. – Carson63000 Jun 5 '11 at 22:44

To blatantly answer your question:

It might or might not be worth it to draw a class diagram. You need to look at your system and determine what diagrams (if any) would add value to anyone working on the system. If producing a diagram will make the lives of developers, testers, or maintainers easier, then the diagrams should be produced. If they don't add any kind of value of anyone working on the system, then don't spend the time or effort on the work. If the system already exists, you might also want to consider reverse engineering to produce diagrams to allow a new developer to understand the system in less time.

In terms of costing more money, yes, creating diagrams for your system up front costs money as developers spend time creating them (and time costs money). However, this up-front (start of project in a sequential process or start of an iteration in an iterative product) cost can be off-set by the idea that having something that can be reviewed for mistakes, errors, or misunderstandings earlier in the development cycle. A mistake created in design costs more to fix in development, testing, or after release than it does to fix before you leave the design phase.

You explicitly mentioned class diagrams. Yes, class diagrams are widely used. But it's important to show things, but show the right things. Other diagram types can show some interesting views over the system, depending on the system that you are building. Sequence diagrams can show complexity, cohesion, and coupling in a system. Component and Deployment diagrams are useful when building distributed systems, to show the connections between each node. Object diagrams show how the system is going to behave under certain conditions at runtime. Activity diagrams can be used to show business logic and workflows. The list goes on - each diagram shows a particular view of the system, and each view might (or might not) add value to developers, maintainers, and testers.

The strength of UML is in its consistency. It provides a set of symbols that are required to model an object-oriented software system. Using this allows everyone to get on the same page, with reduced ambiguities and confusion across the team. Using words and sentences to describe a system leads to misunderstandings and ambiguities. With UML (as long as you use the standard notations and everyone on the team knows those notations), it becomes far easier to communicate the intended design, as well as actual implementation, of the system. If you are working alone, this isn't so important. However, on a team, it's important for everyone to be thinking of the system in the same light, and UML helps to provide a standard language with the constructs necessary to do this.

So far, I have never used the full extent of UML, either at work or in my personal projects. However, I do use UML notation to put my thoughts on paper and work through them, trying to make sure that they will work before I start coding. It's much easier to grab a piece of paper or use a whiteboard and make changes to sketches than it is to code once it's been written. This has also be my experience on most of the teams that I've been on, with a few exceptions. This goes for all kinds of diagrams, ranging from class diagrams through activity diagrams. It depends on the problem that I'm trying to solve and what I'm having problems thinking through.

In terms of the cost of using UML up-front, you are going to be spending the time to sit down, either as an individual or team and creating diagrams. Steve McConnell gives some numbers from Capers Jones and Barry Boehm (among others) in his books, Rapid Development: Taming Wild Software Schedules and Software Project Survival Guide: How to Be Sure Your First Important Project Isn't Your Last:

  • Rework of defective requirements, design, and code is 40-50% of the cost of development.
  • An hour of defect prevention will safe 3-10 hours of defect repair time.
  • Cutting design time might seem to reduce the cycle time of the project. However, any time cut will be paid back with interest later in the product.
  • An error in requirements or architecture tends to cost 50-200 times as much to correct late in the project as it does close to the point where it was injected (there's a graph showing this on p. 29 of the Survival Guide).

If you are using UML to capture your design decisions and adequately reviewing (a design review is very similar to a code review, but you look at the design documents and diagrams instead of code) and discussing those designs in a clear, concise, and unambiguous manner, then you should be able to find and remove defects early in a project or iteration. Discussing designs can reveal misunderstood requirements as well as designs that aren't able to meet all of the known requirements. Although it does require time, it'll save time and money down the road.

| improve this answer | |
  • First of all, thanks for this amazing answer. I guess I've been with the wrong companies or I might not have enough experience but, in your opinion UML does get used often by companies? Even though it costs time(a.k.a. money)? – Kevin Jun 5 '11 at 13:15
  • My experiences are in the defense and intelligence industries (mostly US government and defense contractors), where there is significantly more up-front planning, even in more agile projects. In my experiences, at least informal models are almost always produced. A little time and money up front saves quite a bit downstream, especially when you are dealing with mission critical software, or components that might be integrated with a mission critical software suite. – Thomas Owens Jun 5 '11 at 13:24
  • +1 Do it if it is useful to someone, but don't do it for the sake of doing it. I've produced design documentation before and given it to a group that had always demanded it, but never received any in the past. Once they got my document, they didn't know what to do with it. It may prove helpful in the distant future, say when you hire new developers that work in that area, but that would fall in the maintainability and readability categories by then. As Thomas mentions, at that point, reverse engineering to a diagram may help in certain cases. – Michael Dean Jun 5 '11 at 13:35
  • I just added a discussion of cost/time citing Steve McConnell's Rapid Development and Software Project Survival Guide. – Thomas Owens Jun 5 '11 at 16:37

I tend to think of UML as a method of communication rather than documentation or design.

I almost never create UML diagrams for myself, because if I am the only consumer, then I can just use a quicker shorthand that I know I will understand. But that doesn't work when a lot of people are involved in a project.

Different types of diagrams are very useful when dealing with different audiences:

  • Behavior diagrams (in particular, Use Case and Activity diagrams) are invaluable when you working on requirements with project stakeholders; you need to be able to understand, and prove that you understand, the business or domain.

  • Interaction diagrams (sequence, timing, etc.) and component diagrams are a great way to disseminate design concepts within a software team. I always hate seeing projects where there's documentation for all of the individual components but nothing explaining how it's all supposed to fit together. Would you know how to assemble a car if you found all the pieces strewn about a factory floor?

  • Package and deployment diagrams are useful if you're planning to hand the project off to an IT team for support, although they are usually not comprehensive enough by themselves.

  • Class diagrams are helpful if (and generally only if) you are using a modelling tool that can generate code from the model and synchronize code changes to keep it up to date. That gives you some flexibility in your workflow - you can switch between the "low-level" (code) and "high-level" (model) views if you need to (for example) write unit tests vs. hash out general concepts. As programmers we are already doing this in our heads all the time; doing it on-screen is the next logical step.

  • Other types of diagrams, I have to confess, seem to be a lot less useful. Object diagrams I will do, but usually on a whiteboard as a visual aid, not as permanent documentation. Profile, composite structure and the like are just way too low-level to bother with; most of the time, the code itself does a better job of documenting those things.

In conclusion: Don't ignore UML entirely, but mind your audience. As others have said, there's no sense in creating diagrams just because, but when you're taking on duties other than pure coding (PM, architect, analyst, etc.) you'll start to find them indispensable.

| improve this answer | |
  • @Aarounaught: +1 And thanks for explaining the different types of diagrams, their uses and when to use them. – Kevin Jun 5 '11 at 16:04

Apart from anything else, designing class hierarchies is not a good way to design software. Inheritance should be the last tool you reach for, not the first. And it's unfortunate that we have ended up with UML as a standard - IMHO, Jacobson's original Objectory notation was far superior to the over-complicated UML.

| improve this answer | |
  • Do you have a link to this 'Objectory Notation'? Or could you expand on the subject? Google didn't get me any results. – Kevin Jun 5 '11 at 13:17
  • @Kevin I'm damned if I can find anything good either! Jacobson wrote a book on the method (this was before he joined up with Booch and Rumbaugh), but I can't remember the exact title, and it doesn't appear in any of the lists of his books. – Neil Butterworth Jun 5 '11 at 13:33
  • I should point out that OOSE (which was the other name of the Objectory method) came out just prior to the big take-off of the Web, so their may not be many historical links so far back. – Neil Butterworth Jun 5 '11 at 14:10
  • Ah, that's too bad. Thanks for attempting to dig it up :). – Kevin Jun 5 '11 at 14:16
  • Nice post Neil !! – UML_GURU Jun 9 '11 at 9:17

IMO it's worth it to sketch UML diagrams when discussing parts of an application with teammates (or even for yourself; how I miss having an office with a large whiteboard!). Formal UML diagrams that must be followed, not so much (but disclaimer: I prefer the "agile" method of development, although not true "Agile" with the capital 'A').

So to answer your question, yes I often create a UML sketch (not so much a true UML diagram with all the bells and whistles, but a basic class outline with some interaction notes) before I start development. It's not normally kept around as an code artifact, though; it's usually scribbled on a piece of paper or a whiteboard.

| improve this answer | |

I would say that there seems to be a dilema on how to use the class diagram. Should it be a Model Driven Development from model to code or multiple iterations in which the code drives the UML. I think that a new trend in UML has started in which it is a kind of Code Model Driven in which UML is only a viewer of your code.

UML class diagram should follow code by reverse engineering any change immediately to update the diagram. If new demand then UML could also be used to create code faster and better but this should be incremental and not full project generation each time as it is today!!

| improve this answer | |

Not the answer you're looking for? Browse other questions tagged or ask your own question.