How deep is enough to represent an algorithm in UML sequence diagram?

Question

I have three simple classes. LoginController, UsersCatalog and User. UsersCatalog has an array of User. I have to represent a simple process of login.

LoginController has a method login(username, password) that simply calls a method authenticate(username, password) with the same parameters.

Now, it's obvious that the method authenticate seeks for a matching User object and returns it. The question is: Is it necesary to represent the seek algorithm? Isn't representing the seek algorithm too much low level?

In the other side, the access to User class is inside the seek algorithm, so if i don't represent it, then i don't represent the access to the User class.

This is part of a wider question. There are any criteria for how deep is enough to represent an algorithm in UML squence diagram?

Answer 1

There are 2 things to consider, in general:

• The intended audience of your UML documentation
• How critical the algorithm is to the success of the project

Are you creating these diagrams as part of a design review for non-technical (or rather, non-software) customers? If yes, then do not bother including the algorithm. Its too low level, and you will lose the audience.

Will the diagrams be used as overall reference for maintenance programmers? Assuming there is nothing special, new, or technically innovative about this seek algorithm, then don't bother. Comments could be enough.

Alternatively, for some reason, it could be vital that the software perform this seek efficiently. Or reliably. Or the algorithm itself is special, new or technically innovative. In that case, document it in whatever form is appropriate - pseudo-code, UML sequence diagrams, etc. If it is important to the success of the project, then the diagram is likely to be referenced in the future.

Answer 2

Sequence diagrams are good for specifying the order of message exchanges between principle objects of interest: User, LoginController, ... etc. When an object receives a message, the reception should cause some logic internal to the object (specified by the object's class) to run. The algorithm that describes what that logic does is not documented in the sequence diagram. It might be documented in an activity diagram (flow chart) that is linked to the class. If you wish to visually describe the algorithm, use the activity diagram.