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?
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.
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.
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.
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
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.
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.
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.
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.
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:
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:
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.
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.
Design will save you time, by using known patterns for recurring problems.
If you work in a team, design is necessary to discuss solutions, to transmit ideas, and very practical but necessary, to distribute work.
"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?