I'm in the middle of a project and I was asked to write UML diagrams (use cases,class diagram,etc). The project isn't very complex.

I was wondering if this be a waste of my time? Should I just be doing other fun stuff like writing code? And when is it not ok to build something without going through all of the conceptual phase? Is it all about complexity? And if so, how to measure it?

  • You might be interested in this post: programmers.stackexchange.com/questions/58084/… – c_maker Apr 15 '12 at 11:13
  • 15
    Sorry but I find UML "technical crap", time waster and .. Ok, I will stop here. I feel better now. – Chiron Apr 15 '12 at 13:23
  • 2
    "If it takes you more time to design it than the customer is willing to pay for it, you are over designing" - Can't remember who to attribute it to, but this is a good guiding thread to guess "whether" it should be used and it would be worthwhile :) – PhD Apr 16 '12 at 6:00
  • 1
    "Should I just be doing other fun stuff like writing code?" You mean: "other stuff that contributes to the bottom line of the project like writing code" surely? – StuperUser Apr 19 '12 at 10:43
  • Of course you do, and don't call you Shirley. – StuperUser Apr 19 '12 at 10:43

20 Answers 20


I was a big fan of UML a while ago. I'm even OMG certified. I used it extensively in large enterprise projects I was involved in.

Today, I stopped UML almost completely. Sometimes, I use the sequence diagram that I find very useful to describe interactions between systems, but no other diagrams.

I now prefer working with user stories, supported by both (only) necessary documentation written by product owner (or analysts) AND his (their) dedication to the development team to give more details as needed.

UML is a tool you can use, but it's certainly not a critical factor for the success of your projects. After many years, I now think the critical factor is the development team, no matter which tools it uses.

  • You said you are OML certified. What is OML? A typo? – BЈовић Apr 15 '12 at 12:52
  • Yes, it was OMG for Object Management Group, the organism behind UML => uml.org – user2567 Apr 15 '12 at 13:10
  • 12
    +1 for the last paragraph. When it comes to diagramming software system, UML is great since it's standardized and should be well understood by other software developers without explanation. However, it's just a tool and you might not need that tool, depending on the people building the software. – Thomas Owens Apr 15 '12 at 14:38
  • 14
    The first paragraph is much funnier if you just read OMG with its usual meaning. – JSBձոգչ Apr 15 '12 at 16:26
  • @Pierre303 I agree, that there are other options than UML. But the question is also about using specification/documentation tools in contrast to pure coding. Does "no matter which tools it uses" mean "as long as the team actually uses tools for these tasks"? Do you use user stories even for "[not] very complex" projects or are those a waste of time in those cases? – scarfridge Apr 17 '12 at 20:14

Planning is critical, but as the famous strategist Carl von Clausewitz warns

No campaign plan survives first contact with the enemy

So its not a huge waste of time for planning how to initially attack the problems. But likely a waste of time for documenting your code for future programmers. To use a military metaphor, you need a battle plan, but you wouldn't give that plan to historians to use as an after action report.

More concretely, you can use these diagrams to communicate your intentions amongst your team and think about your plan of attack before and during the project. But odds are that what you come up with will need to be tweaked as you code and learn more about the problem. Almost always your initial plan/design needs to be altered because you can't know everything up front.

  • 3
    But likely a waste of time for documenting your code for future programmers. If a project wants to use UML as a form of documentation, it's typically created using reverse engineering tools. There are various tools that can generate class and sequence diagrams (and sometimes a few others) from source code, and the output of these tools is captured as documentation. – Thomas Owens Apr 15 '12 at 11:32

I think UML diagrams can only be useful if they express something in a higher level of abstraction than your code.

Writing UML just for the sake of writing UML becomes unneeded bureaucracy and makes the project and the code less adaptable to changes with no benefit whatsoever.

For example, a UML class diagram showing all the classes on a package, with all their attributes and methods --something that can be easily auto-generated-- provides no value at all: it is at the same level of abstraction than your code. Plus, the code will most surely be a better source for that information because it will always be up to date, and it will probably be documented and organized in a way that is easier to know which methods/attributes/things are more important.

On the other hand, if you have concepts of a higher level of abstraction than what can be expressed expressed on the code, documenting those on a diagram can be a good idea.

For example, a diagram showing the higher level abstract modules on a complex system, with their dependencies and maybe a little description of their responsibilities and what package/namespace they map to in the source-code can be a really useful for a new team member that needs to be introduced to the project, or can also be used to figure out where a new class/functionality should be thrown.

Another example of a useful diagram could be a sequence diagram showing the high-level steps to be taken in a communication protocol. Maybe each step of those have it's little quirks and complexities, but it's probably enough to describe them in the code itself. The higher level diagram can help a programmer to understand the "big picture" of things easily without needing to worry about the complexities of each interaction.

Anyway, those are just some examples; there are lots of cases where a simple diagram can be of a lot of help. Just remember that you should be doing them only when you cannot express something in the code itself. If you find yourself using UML diagrams to explain the source-code itself, make the soruce-code more self-documenting instead.

Finally, some of the general rules that apply to code can also apply to diagrams: avoid repeating yourself, keep it simple, don't fear of changing things (just because something is documented on a UML diagram doesn't mean it can't be changed) and always think of who will be reading/maintaining those diagrams in the future (probably your future-self) when writing them :)


UML has value if team members collectively understand it and consider it a useful way of summarising and communicating design decisions. You don't need to know it all, just that subset that the team finds useful.

Also, you don't need to draw perfect, polished diagrams. A roughly-sketched sequence diagram on a whiteboard or a class diagram in which classes are post-it notes stuck to that whiteboard might be sufficient, depending on the context.


I once worked on a gig where I needed to manage a team of contract developers overseas.

Some of the stuff they were producing was pretty horrendous (a common symptom of remote contract coders - they don't really care a lot for your code, they just want to get done fast).

To manage the project, I found myself producing UML diagrams and handing it to them to code. It was very successful - it didn't take me that long to write a program in UML, much faster than in Java, and it was something the contractors could follow and be measured against.

One caveat - they did at times want to become creative and deviate from my models, however in those cases they were actually correct, and over all the UML improved the quality of the final product

  • +1 - One of the key benefits of modelling is to be able to create, change, understand and explore different ideas far quicker than you can do it in code. – Dunk Apr 16 '12 at 13:23

If someone asked you to prepare UML diagrams and that someone is paying your salary, then it is not really a waste of your time. It may or may not be a waste of that someone's time.

If that someone is planning to understand your project by reading your UML diagrams, then it probably is not a waste of their time.


I find it useful at the initial design stage to get ideas on paper or on the whiteboard. I've mainly used UML class diagrams, without a strict adherence to the standards. Its useful to revisit your UML original design when you're part way through and also at the end of the project. It has helped me to look at a codebase at a higher level of abstraction that you ever can just by reading through code, and has even helped to spot potential bugs.

There's a good point made here by ragu.pattabi distinguishing between two kinds of UML ...

I think the agile flavor of UML (e.g. quick white board sketch) is more successful than the waterfall flavor of UML (e.g. elaborate diagram with all gory detail for documentation, code generation, etc to make the document savvy managers happy).

When UML was seen as a 'must have' skill (10 years ago or more) I was probably against it due to the opinionated views of its many fans at the time. But now that its fallen out of favor, I find myself seeing it for what it is - a useful tool that has merit but is not the silver bullet of software development.

  • 1
    +1 - The only times I saw UML as a time waster was when people tried to adhere to the "standard" and worse, to actually generate code from it. The proper use is to use it as a communication mechanism and a way to explore different ideas, even if it means "tailoring" it to suit your needs. It is far more efficient than coding first, unless the application is trivial. – Dunk Apr 16 '12 at 13:27

I use UML (or sth similar to UML :)) when I talk to friends about something we're about to do. To discuss ideas. Not to prepare UML project that will autogenerate code for me. I can't imagine creating my classes in UML then generate code and not tweak it later. This never happens. So you will have to bring changes from code to UML. And when I use UML I draw on whiteboard or paper. Never in tool like Enterprise Architect.

The only reason to document my whole code in UML would be a contract where client demands it. For example when he want's to have an option to change software shop after part of software was finished.


Project work documentation is a fundamental deliverable of a professional project. How much is enough? Well it depends of course on many factors. However, in my opinion, use cases, class diagrams, process flow diagrams, etc. are not waste of time at all. They have value in various project phases. The only problem with documentation is usually resources.

Some programmers consider documentation is a waste of time. But this is not true. If you view documentation as a display of your design and system rules in an elegant and clear way, you may come to appreciate it more. Also, one needs to put one's self in the position of the people that need to maintain the system. To be thrown 500 files of code and to be asked to fix the problems with them is kind of bad but not uncommon.

I suggest you allocate time in your project and produce the diagrams in cycles. The first would cover the high level aspects of your project and subsequent levels could dwell more on the details.

Use cases in particular can't be deduced easily from code (unlike many other aspects of a system). Make sure you do those.

  • -1: If you view documentation as a display of your design and system rules in an elegant and clear way: Nope, I never do; because it's always obsolete. // I'm not sure where you live, but on Planet Earth, software evolves far too fast to justify "professional-grade" documentation. – Jim G. Apr 15 '12 at 13:49
  • @JimG. That can be true or untrue, depending on how detailed the documentation is. If you keep your documentation high-level (components, major details of major classes), then the documentation won't grow stale quickly. If you manually document every member of every class, then your work will be useless pretty quickly. – Danny Varod Apr 15 '12 at 14:53
  • 1
    @JimG., I am sure you are not alone in thinking this way. The fact that software changes, does not make the analysis, design and implementation documents entirely obsolete. Such knowledge evolves during the system life cycle. If you had to hand over systems to organizations that do IT Audits, you'd have to show documentation and not just the code and the binaries. – NoChance Apr 15 '12 at 15:03
  • @Emmad Kareem: Regarding orgs that do IT audits - Most of that documentation is perfunctory and intended only for the audit. Most software devs won't trust it. – Jim G. Apr 15 '12 at 22:11
  • @JimG., what you have described in your last comment is a situation that I would like to see go away. I would love to see software development become a more predictable business that will make developer's life better and will reduce the risk organizations swallow because they don't know of the dangers they need to face. Anyway, I guess it is a long subject but interesting one (to me). – NoChance Apr 15 '12 at 22:31

UML is a tool, nothing more, and whether it is useful or even crucial depends solely on your development and design workflow. There are many ways to Rome, and some of them involve UML, while others don't.

If your workflow relies on UML to document or plan your architecture, then dropping it would be silly. If UML is the best possible way of communicating the project structure to other team members (in the wider sense), then by all means, use it. But if the project works fine without UML, then making UML diagrams just for the sake of it is nonsense.


I have some thoughts about this. Language can be used and abused, compel and distract, trigger and lull. UML is just another language suited for a specific set of problems and just as any other language, it'll take time and effort to learn to speak it fluently and understand it correctly.

The decision on what to communicate is incredibly more important than the language it is communicated in. UML will not magically make your bad designs understandable. Just like any other language, it is easy to get lost in details or leave too much to the imagination.

UML got a bad name because of the numerous horrible IDE's, allowing round-trip prototyping, click-intensive graph manipulation and the difficulty of changing anything. UML 2.0 might be complex enough to satisfy certain academics, but its meta-model does not seem to attract many practical applications.

Still, I use UML from time to time. To evaluate a high-level design (a good design has complexity on the fringes and simplicity in the centre). To communicate an idea to a colleague and receive feedback. To find hidden relations, normalize, etc. But it's always a reflection of something that's already in my head. Generally, I draw UML with pen and paper, preferably away from any computer. If necessary, when a design crystallizes, I make a visual representation in a drawing program.


UML is absolutely fantastic to get a graphical view of your architecture using a class diagram. Interaction using sequence diagram is magic for me. The problem is not therefore UML but MDD for me.

I mean that if UML is a viewer of the code then it is really helpful for documentation purposes but certainly not for code generation. Project should be code centric and certainly not Model driven centric. UML should used at implementation stage using a live code and model synchronization.I mean not only at requirement level which requires too much investment for small return in productivity and quality.


I find them highly overrated. I consider them the only pictures that don't paint a thousand words.

  • Put paint and a brush in the hands of someone unskilled and all that results is a mess to clean up. However, put paint and a brush in the hands of an artist and art is born. Same goes for UML diagrams. – Dunk Apr 16 '12 at 13:39

UML is only of value if the people designing the system cannot write the code themselves. ie, UML is a 'language' that communicates the architectural concepts to someone else, now if you're the person who is designing the code and implementing it, then why would you need to show yourself what it is you're going to do?! Get on and head straight for the coding instead. You'll still have to document what you did later, but the overall efficiency is quicker.

But, if you were a system architect wanting to tell your outsourced team of developers what you wanted, then you'd have to tell them somehow, and that's where UML comes in. However, I think that there are plenty of alternative means of performing this task nowadays, and frankly, the complexity of the UML diagramming means everyone has to understand how to read it, which is somewhat self-defeating if they don't.

  • LMAO, black/white? Your "suggested" method of development is the reason I am called in to clean up and fix disastrous projects so often. The code is not the design. There are few people who can create even moderately complex systems (I guess I have to leave that statement as stand-alone). And there are far, far fewer that can do it by jumping straight into code. Also, you may have a "broken" system quicker, but you won't have a "working" system quicker by jumping straight into code. But I guess it all depends on the type of projects you have. If half working is ok, then your approach is fine. – Dunk Apr 16 '12 at 13:19

I was never a fan of UML, but I have come to value a good sequence diagram to describe interactions between systems or tasks.

However the class diagram is obsolete before it is born. A rough design does not require UML, and a thorough documentation is better automatically extracted (live) from the code base. Javadoc and Doxygen have completely obsoleted the need for manual class diagrams.

The thing about documentation is that there are two levels:

  • high level (architectural) decisions should be documentation manually
  • low level (entities relationships) facts should be extracted automatically
  • Almost all CASE Tools can reverse engineer your class diagrams. With that said, I think class diagrams are about the most useless diagrams there are, except maybe for showing inheritance and dependency issues (in which case just the class names are sufficient). The most bang for the buck in UML are the sequence diagrams. Unfortunately, no tools do a reasonable job of reverse engineering sequence diagrams. This one lack of capability is the main reason that it is really tough to use UML to document your design as it is. Instead, UML just provides a roadmap prior to implementation. – Dunk Apr 16 '12 at 13:36

I usually iterate between code and UML diagrams. I find that the diagrams help to show the big picture and a solid path forward and they can be changed rather quickly when issues are discovered. Also, when I have the diagrams, the coding tends to become trivial.

Conversely, when I draw the code in pictures it exposes dependency issues and makes design improvement opportunities blatantly obvious, which probably wouldn't have been noticed if we just had the code to work from. In particular, if it is a pain to draw, then it is going to also be a pain to code and a nightmare to maintain.

I have found that iteration is required, because just drawing the pictures always misses important aspects, while just coding results in problematic designs.

However, like another poster said, it all boils down to the people. If they are skilled "using" UML diagrams then UML is invaluable. If they aren't then the diagrams are of no value.

Thus, the answer to your question really is, "it depends". In this case, it depends on the people, the complexity of the project and how important it is that the system works properly.


From my experience the UML is important for the communication between developers about the code patterns and for the architecture in general of the application.


I love diagrams, but if I was asked to make one (especially UML!), I'd ask two questions:

  1. Who is it for?
  2. Do they need it now?

Diagrams go out of date straight away. So unless you're using it to communicate with someone now, it will just rot. And if the person you're communicating with would do better with a text description, or a phone call, or an informal digram on a whiteboard - suggest that instead.


One of the major gripes for me about UML diagrams as I've seen them used so far is that they mostly only tend to serve as "pretty pictures" on someone's wall or as a folded page in a binding somewhere and rarely serve as a baseline for a production code.

In this type of scenario - the UML diagrams (or whatever flavor of modelling language you use) are rarely useful in the long run, as they tend to suffer from loss of relevance as the time goes on and the project evolves. These initial drawings are mostly useless and incorrect in few year's time and having them around is mostly harmful.

That said, using modelling tools (not necessarily UML) is not entirely useless practice, if the models provide actual live and relevant input to the actual running code. If the model description is a useful artifact of the code, it should be treated as code:

Either by using it as a direct source of metadata for making dynamic decisions based on the modeled concepts, or using code generation to generate static code artifacts that get used in the actual working code.


Don't know if the question is about the merit of UML, or about the merit of designing the architecture of programs.

About UML. You usually only need: use cases, class diagrams, and sequence diagrams. Simple and easy, although you could do it certainly with your own types of diagrams. In this regard UML is a standard everyone will understand.

About designing programs.

  1. Every program has a design, even if you don't plan it. When the code is written, just reverse-engineer it. If you didn't planned it, bet it will be a bad design.

  2. Design will save you time, by using known patterns for recurring problems.

  3. If you work in a team, design is necessary to discuss solutions, to transmit ideas, and very practical but necessary, to distribute work.

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