UML Class Diagram: How to describe method functionality?

Question

Recently, we have learned about UML class diagrams in university and I began applying that knowledge to my work projects.

However, I am still unsure how or where I am supposed to describe the functionality that a method of a class offers.

In code, I would simply put a docblock above a method in which I describe that method's purpose. Where would I put that information in a UML diagram?

I can think of several options

• Object Constraint Language, either in a note on the class or a separate document. However, I don't think I can express the whole functionality this way
• A note on the class that contains the same verbal description that I would put in a docblock. However, this way I would have a lot of notes in my diagram I guess
• Accompanying diagrams like sequence diagrams or communication diagrams, but that seems pretty verbose
• Use case diagrams/descriptions. Seems also pretty verbose if a single sentence as in a docblock is enough to describe a method's purpose.

So I am wondering: How would I 'translate' a docblock description into UML?

Answer 1

In a class diagram, you don't typically show the functionality of a particular method. That's not the purpose of a class diagram. You're right that you can use Object Constraint Language or pseudocode in a note, but I don't think this is done often.

Consider the mode in which you are using UML. If you are using UML as a blueprint, you're going to want the verbosity of a different diagram type so that you can clearly specify the intended behavior to someone else. Sequence, activity, and communication diagrams all can be used to represent the flow through one or more methods. But if you are using UML as a sketch or notes, then perhaps you don't need that extra detail of a separate diagram because the method signature (name, input parameters, and return type) are sufficient to understand the purpose.

Answer 2

However, I am still unsure how or where I am supposed to describe the functionality that a method of a class offers.

This is a valid concern. I should be able to look at your UML diagram and have a fairly good idea what the methods do.

In code, I would simply put a docblock above a method in which I describe that method's purpose. Where would I put that information in a UML diagram?

Well here's your problem. You're going about this all wrong.

• Object Constraint Language, either in a note on the class or a separate document. However, I don't think I can express the whole functionality this way

No.

• A note on the class that contains the same verbal description that I would put in a docblock. However, this way I would have a lot of notes in my diagram I guess

No.

• Accompanying diagrams like sequence diagrams or communication diagrams, but that seems pretty verbose

No.

• Use case diagrams/descriptions. Seems also pretty verbose if a single sentence as in a docblock is enough to describe a method's purpose.

No.

So I am wondering: How would I 'translate' a docblock description into UML?

You don't.

UML does a wonderful job of forcing you to look at your design from the point of view of the interface you're offering. You're looking at your interface and realizing it's confusing so you want to explain it. No.

UML Class Diagram: How to describe method functionality?

Give the method a good name.

If that's not enough then you need to redesign. Stop making me look inside methods to understand what they do. If I look inside and am surprised by what it does then you've got problems that a doc block isn't going to fix. At the most a doc block should confirm what I suspected before looking inside.

The only thing I should learn when looking inside is HOW it does what it does. That info doesn't belong in your UML design anyway. That's an implementation detail.

Answer 3

However, I am still unsure how or where I am supposed to describe the functionality that a method of a class offers.

In code, I would simply put a docblock above a method in which I describe that method's purpose. Where would I put that information in a UML diagram?

Use good names

UML is a modeling language that is visual, generally more so than source code. However, good naming strategies apply equally to class methods, regardless of representation (UML or source code). A good name captures the "what" of a method. Usually, this name is going to fit well with the name of the class. It's the principle of strong (high) cohesion.

If you use good names, you won't need much explaining! I'd suggest using the source code to comment things like authors who modified the code, dates, etc.

You can apply refactoring to UML models (e.g., sequence diagrams which results in new class diagrams), just as you do with source. Renaming methods as well as extracting methods is a way to make your solution more understandable (and even more reusable). Again, this goes along the lines of high cohesion. Beware, however, that as you refactor, the docblocks you wrote (in text) will not update themselves. It's easy for the solution to become inconsistent with your docblock.

So I am wondering: How would I 'translate' a docblock description into UML?

Docblock descriptions are basically comments. The best way to write comments is a controversial topic in software engineering, since it's very easy for comments to become inconsistent with the code (or the model, if you're using UML).

Sequence diagrams for a method will show the "how" of the method, and are better than any docblock because they're visual and should be consistent with the actual solution. Some UML tools allow generation of sequence diagrams from the source code (or vice versa), so you can see immediately how a method works. However, the quality of this generation is subject to the tool and the complexity of the method.

If your method is really doing something not obvious, a UML note would be a good way to show those things, just as line comments are used in a programming language. Here's an example from Craig Larman's Applying UML and patterns book: