UML Class Diagram – How to Describe Method Functionality

class-diagramdocumentationuml

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?

Best Answer

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.