Class Diagrams - questionably useful?

Question

How is a class diagram actually any different to just looking at the class definition with all the functions collapsed? I've been asked to write some and realized that this is all just .. read the source .. it has comments. What's the point of a class diagram, how is it different to even minorly commented definitions, and what makes a good class diagram better than others?

Edit: Yes, the source already exists, and did so long before the class diagrams.

Another edit: People have been talking about visual vs textual tastes. That's not the definition of class diagram I was given. It's still purely textual. The sample class diagram is a bunch of text, that resembles the source code with the function definitions cut. That's the reason that I asked. If it was a genuine diagram, I could understand.

Answer 1

A good class diagram clearly shows each classes responsibilies and associations - at an appropriate level of abstraction.

Class diagrams are useful because they allow you to design at a higher level of granularity. Operations drawn on a white board are easier to change than source code. It also clearly shows associations through lines, rather than leafing through code.

They're helpful in that they are a segue from conceptual ideas to source code. They let you say more with less.

Answer 2

If you have one or two classes, that does not make a diference. If you have a complex object model, things change.

And, at least for me, is easy to look first at a diagram in order to look for what I want in stead of looking at a bunch of source files. Also seeing the classes on a picture and their relations helps to understant the ideas of the project.

Answer 3

If the source already exists, I guess it's the old adage, "A picture tells a thousand words". For someone not familiar with the source, a diagram may help them to grok the overall design quicker then reading the source, no matter how well documented. Some people are more visual than others. Personally, I'd rather have the source. Like many things, it's probably a matter of taste.

Edit:

I thought the definition of a diagram was that it is visual. However, if it's just a bunch of text, then the only point I can see is that it provides an overview of intent without the unnecessary implementation details.

Answer 4

I'd rather have source. Given that, I can always reverse engineer it.

You have to ask what UML is for: it's just a communication device, a way to get your ideas across to other developers. If UML is helping, great. If it becomes another burden to maintain, prefer working code with good unit tests.

Answer 5

The difference between looking at a diagram and the source is that you don't need to process as much data when looking at the diagram (a picture) than when reading the source (says thousand words).

In my experience I've found class diagrams to be very useful when I'm not familiar with the architecture of the software. But class diagrams don't replace the need for source code and proper documentation, they're just a communication and productivity tool that complement the methods I mentioned before. Their intent is to understand the software architecture. not to replace other documentations. How useful a class diagram is depends on its quality and the complexity of it and the source code.

Don't put too much detail into the diagrams. It makes them confusing. You'll want them to communicate relationships, not API and a list of methods.

They also help to see when and where to refactor code. Use class diagrams along with proper documentation and you'll be all set.