UML / Diagramming

#21

Quote:In my experience, UML is only good for reasonably small and simple projects.

You have it exactly opposite to the truth.

What would a UML and design document do for a small project?

For small projects, a programmer can easily read the whole source code and understand the entire design without needing additional documentation.

UML is unnecessary for small and simple projects.

Quote:you can just look at the higher level classes to get an understading of what's going on.

How do you know which classes are higher level?

The larger the project and the more complicated the design, the more important it is to write good design documentation.

Quote:And diagrams don't really help people get a much better understading of the code base, you tipically end up with thousands of blocks and millions of connections.

You've obviously either not written or read high quality UML and software documentation.

You would only get thousands of blocks and millions of connections if you were attempting to look at an entire collaboration diagram for all of your classes simultaneously.

You are absolutely correct in your statement. Such a poorly written diagram wouldn't help anyone understand the design.

On the other hand, if you drew relevant subsets as diagrams to augment the related textural or verbal documentation then understanding comes more quickly than if you tried to create a document with just text or dialog alone.

If you've seen oxygen's collaboration diagrams then you'd understand more of what I'm saying. You get nice, neat small snapshots of a particular class and all other classes with which it interacts.

High quality sequence diagrams are also not cluttered with useless function calls. As a designer, you should only document the relevant pieces of information.

This is primarily why a tool can't do this very well.... tools generally can't distinguish between relevant and irrelevant program flow.

Back in the late 70's, 80's and even part of the early 90's, it was very difficult to communicate design. Mostly we used block diagrams, flow charts and data flow, which are sometimes useful, but they are way too detailed for overall design documentation.

Using these older styles of documents and diagrams, you would end up focusing on implementation artifacts instead of seeing the design for what it is.

When Grady et al came up with UML and the Gang of Four came up with the initial names for design patterns, finally we had the tools necessary for effectively communicating design. Now we have the vocabulary and standardized diagrams that everyone can understand.

It's tough enough explaining a design without also having to explain your vocabulary and diagrams.

Why do you think mathematicians have standards on drawing formula's and standardized vocabulary? For exactly the same reason we use UML and names of design patterns.

Without standards, not only do you have to explain the design with extensive text, you would also have to explain the vocabulary and additional diagrams.

Quote:Besides, the beauty of languages such as C++ is that you can structure your code so that it's built on multiple layers, and you don't have to understand each line of code, or what each low level class does, if you don't want to... you can just look at the higher level classes to get an understading of what's going on.

I think you're speaking for of documenting the implementation and less about documenting the design.

UML is a way of documenting software design through the use of standardized diagrams.

The only reason you might not want to use it is if you didn't want to document your design, so possibly that's what you're saying.

Or maybe you assume that everyone is starting with a poorly thought out design. If that's the case, then I would have to agree with you. Why bother documenting it since you will end up drastically changing it later?

If you start with a great design from the beginning, less of it will change over the lifetime of the project, and therefore less of the documentation will have to change.

I guess it all boils down to the talent of the software designer and his skills in using UML and writing documentation.

Talented designers

Use UML in your design documents because the diagrams will help clarify your design.

Untalented designer

Don't waste your time documenting your designs that are destined to be either thrown away or dramatically changed.

But, when you're finished and you are pleased with your design and you would like to share the design with others, it's a good idea to document it. UML is a great way to help augment your documentation.

#22 As long as we are resurrecting a five year old thread, count me among the UML lovers. It is the only way to manage a complex project. While there may be something to the argument that you be changing your design later, the more thought that goes into the design, the fewer and less painful the changes later. Also, it makes for handy documentation when you are actually coding and can keep you from writing spaghetti code hacks.

Edit: This package would degenerate into a mess if I did not use UML:
i70.photobucket.com/albums/i109/davidhstocker/SourceForgeAngela/ClassDiagramRMLP...

#23 @Michael Bartmess - Sorry, I guess your question was never really answered.

This is the best documentation I've seen so far.

But, it is missing things like the class collaboration diagrams. Maybe we could talk someone from Garage Games into turning some of these options on and re-generating the HTML?

#24 TorqueScript sequence diagrams for starter.fps
Download the sequence diagrams here
Free Jude UML Modeller

#25 Awesome, thanks Dunsany.

#26 I'd love to live in a world where you design your classes / game once and don't change it after that, because your design is perfect in the first place and you can think of any possible issues and optimizations in advance.

That'd be great, but that's not the way it works in the world of game development as i know it. The code I work with changes pretty much every day. That's not just the implementation, but the overall design itself. In the end, only the code is in sync with the code.
But what do I know... good luck with your UML documents, have fun maintaining them :)

@Hokuto: Hi, nice to see you again on these forums!

#27 I change my design frequently as I realize that something does not implement well, that I underdesigned or overdesigned something or I simply have a better idea. Keeping Visio in sync is a bit of overhead, but I really do find that it helps me keep a 10,000 foot overview. It has already saved my bacon once when I changed the script level identifier for how sim-object templates reference each other.