3

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?

  • I'm not a UML expert (so I'm posting as a comment rather than an answer), but I suspect for any non-trivial method: sequence diagrams, communication diagrams, process diagrams, or even good ol' flow charts are probably the way you should be doing it. – FrustratedWithFormsDesigner May 15 '17 at 16:24
  • 3
    Congratulations, you (re)discovered the fact UML is pretty bad for describing the semantics of code. – Doc Brown May 15 '17 at 16:52
5

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.

  • In the most cases, the method name and signature etc. are indeed enough to convey its purpose. I was wondering because i. e., when I have a Facade that enables a user to perform a fairly complex task via a single method call, I figured just having the name and signature might be too little information. However as I just recently realized while working on a project, those rules that apply to less complex methods should still apply to more complex ones too, no matter what's happening under the hood. – Subsurf May 26 '17 at 10:18
7

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.

0

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:

enter image description here

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.