UML

I'm not sure if this is the right place for this thread, so if it's not, please move it. Thanks.

UML is something that was lacking in my degree curriculum and the further I go in my career, the more I realize how important it would be as a tool, if I was more familiar with it.

What I would like to ask is;

How many people emphasize the use of UML in their daily programming and development?

What resources would anybody recommend as a great way to get more familiar with UML?

Yeah, okay, I already did Google it, and I found a few good guides and references. I found a nice cheat sheet, but most of what I found was 100+ to 500+ pages of hard reading.

Is this something that I just need to get my hands dirty with? I will buy a copy of OmniGraffle and I can figure out how to use it, but I need to have some clue as to what icons mean what, which lines mean what, etc.

(Dec 4, 2012 02:46 PM)bmantzey Wrote: the further I go in my career, the more I realize how important it would be as a tool, if I was more familiar with it.

Really? It always seemed useless to me, so I'm curious what situation you've found where it would help you... To me, a graph is for summarizing something and making it more accessible to a casual viewer, and introducing a formal language that you need to know in order to understand the graph kind of defeats that purpose.

On the rare occasion that I want to make a graph or chart, I'm quite fond of GraphViz and gnuplot, depending on what sort of thing I need to generate.

Having complicated code with Command patterns, Visitor patterns, Singletons, throwing NSNotifications, and other event driven systems isn't exactly as easy to read as a Maxim magazine!

Documenting my code visually would provide an enormous tool in maintenance the next time I need to make a change (say next year). If I haven't looked at the code in a year, having something visual to refer to would cut the time required in figuring out what the heck I was thinking by a lot!

When I took this job, if there were UML diagrams of all the code, I would have been extremely grateful.

Knowing which controller invokes the next controller and the next and so on makes it much more clear where and how to invoke a new class used to provide new features.

Being able to see where it goes before I dive in on a complicated feature seems to me a MUST when the code base becomes more and more complicated.

Being as how I've also been tackling the issue of project complexity, I recently began adding copious header documentation for HeaderDoc (could use DoxyGen instead). I hate what it does to the readability of the code, but it's only in the header and I've accepted it as a necessary evil at this point.

I noticed while researching DoxyGen that it includes a graphing utility (I think it uses GraphViz) which looks pretty snazzy for OOP type languages. I think you might be able to use it to auto generate uml diagrams for your source code.

I haven't read many good comments about UML diagramming around here at iDevGames. Personally, I don't find diagramming of any sort to be particularly helpful for software development, except perhaps as a quick overview.

I've never found a case where a UML diagram makes anything clearer. I think it's born out of a desire to draw pictures to represent things. Likewise with flowcharts. I guess they are both good ways to keep people busy.

(Dec 4, 2012 03:24 PM)bmantzey Wrote: Knowing which controller invokes the next controller and the next and so on makes it much more clear where and how to invoke a new class used to provide new features.

Everyone has a slightly different idea of what a UML file might represent.. Since it can represent just about anything.

Cases where they are useful could include some of the state-based transitions- like state based AI or program flow. Like this sort of thing isn't too bad:

But really, especially in the last case, it really only has served to complicate the design of that state based AI. There's no clear reason you can go from Gather to Attack, but not Gather to Equip. Should they have drawn a fully connected graph? If you look at each of the conditions moving from idle to the other states individually, you could probably move from any state to any other if the correct conditions are met. Then you don't really have such a rigorous set of transitions that are dependent on the current state... and the diagramming has really only made things more complicated.

Just looking at the diagram... does that help you understand what a CCSprite is? A vertical class hierarchy seems to give you the same information much more concisely. All I really can get from the collaboration diagram is a list of other classes that are *somehow* related to that one, and then you're looking at the docs anyway to figure out what they mean.

(Dec 4, 2012 03:24 PM)bmantzey Wrote: Documenting my code visually would provide an enormous tool in maintenance the next time I need to make a change (say next year). If I haven't looked at the code in a year, having something visual to refer to would cut the time required in figuring out what the heck I was thinking by a lot!

In some cases it might, but what seems more likely to me is that the UML diagram would become a significant maintenance burden in itself. This sort of supplementary documentation has a tendency to fall out of sync with the code it's documenting in my experience, which is going to end up hurting you when you want to reference it to figure something out, because you often won't know if you can trust the diagram to be accurate and up-to-date. However, AnotherJake brings up automatically generating it from your code... If you're able to do that, it solves the two problems above. I'm not sure how much value there is in trying to get your automatically generated graphs to conform to the visual language of UML, though.

My degree unfortunately included a solid amount of UML diagrams. For a project in one course (which infuriates me to even think of it) we had to design a "website" for some business application, but we had to diagram everything about it and make a massive flow chart of every (procedural C!!) function needed to implement the entire program. Up front. Class diagrams (figure that one out), state machine diagrams, activity diagrams, use case diagrams, sequence diagrams... It was ridiculous. Way too much BS.

UML's goal is to be able to diagram everything about how software should be written and how it should work. It comes from the idea that if all of the details and possible decisions can be fleshed out up front, then you can make a specification and then all you have to do is implement that specification. This is where "software engineering" comes from.

The old school (still very common in big industry) methodology is that creating, nay, engineering software shouldn't be any different then designing a bridge or a building. That's crap. Anyone who teaches you this is possible is a moron. This is why software projects with budgets of tens of millions to literally billions fail all the time. The same class that was teaching UML and software "engineering" used a bunch of case studies about projects that failed supposedly due to "insufficient planning and inaccurate requirements." Bull. They failed because software doesn't work that way. Software is organic. It, like the requirements, are constantly changing.

But anyway, I'm straying.

You don't need to diagram anything…
until you come across that situation where it's just too complex to keep in your head when designing/learning/explaining something. "UML" is a bunch of different kind of diagrams. Many have legitimate purposes, some I think are just absolutely useless. The real question is: when should you use them? Don't get sucked into thinking "oh, there's all of this stuff in UML therefore I should be using it and then I'll create better software!" No. A diagram should only be created if it's absolutely needed.

Diagrams are cheat sheets, not documentation.
Consider this: you've designed and created your program, and now you want to document how it works internally for the future. So you polish your class diagrams, your flow charts, and your sequence diagrams. Now the obvious: you need to add a new major feature. This inevitably means adding new code, refactoring a little bit here and there, maybe splitting a class into two, removing another one, adding a couple. You code it all up, test it, ship it, done. But suprise! Software isn't like building a bridge, so this happens every two weeks! More code, more revisions, more refactoring... All of your diagrams are out of date. What good are they now?

Diagrams start to rot
Unless whatever it is that you're diagramming, is going to remain stable and practically unchanging for a very long time, the diagram is inevitably going to be stale, unmaintained, and useless. If a diagram is simple, it almost certainly wasn't worth making. If a diagram is very richly detailed, you probably spent too much time on it. The code is your definitive source for how your program works. Focus on making your code better, rather than your diagrams.

Sometimes you need a diagram to explain how some code works, but in that case UML is no better than whatever other convention you invent in the heat of the moment, and the diagram should be immediately discarded before it gets out of date and misleads anyone.

Using it for design is a waste of time, because problems with the design will become apparent within the first five minutes of coding that can remain hidden through weeks of elaborate planning. Just start coding, and refactor to get design. It's the path of least work.

I worked at an avionics company where airworthiness certification is required on software that controls vital systems on airplanes.

UML and similar diagrams are used all over the place, and maintaining them was a nightmare.

However, I witnessed them be useful... but not necessarily to the types of people that frequent this forum.

They were useful to non-technical people who need to get some very basic bearing on what's going on in the system. And as I learned about new systems that I was supposed to extend, I found them useful to show how data flowed throughout the system - otherwise, I would have had to familiarize myself with a huge, old code base instead of just looking at a few diagrams. We're talking the difference between weeks and minutes.

The FAA - an airworthiness governing board in the USA, and pretty much the recognized standard-bearer worldwide in flight certification - requires things like these diagrams.
And when we're talking hundreds of peoples lives on an airplane, it's good to require some slightly-more-human-friendly representations of the code's logic than diving into thousands of lines of source code.

But maintaining them is truly a pain. For something like a game, where there is nothing as intimidating as flight certification, the value probably just isn't there.

Formal UML wasn't necessarily what we did at the avionics company, either. Formal UML is definitely not necessary to communicate the organization of the systems - lots of different diagramming techniques communicate that.

I think it's always good to take a shot at planning stuff out in advance before writing a single line of code, and if UML or other diagramming tools help, use them. Diagrams - whether UML or something else - can help you plan out a project at the beginning, but when there's no multi-million dollar contract paying a team of people to keep the diagrams updated, it's best to throw them away once you get into the real down and dirty coding.