2

Is it okay to group several Components into a single lifeline for simplicity?

For example, let's say I have a UML Component Diagram, and it's a layered architecture. There are 26 components, one on top of the other, component A to Component Z.

The interface to the system is Component A and the processing is in Component Z. When a message is sent to Component A, the messages flows down the Component Stack all the way to Z to be processed, then the result flows back up to A. Now let's say that component N does something interesting with the message that we want to show on our Sequence Diagram, but the other components are purely passing the message to the next component.

Many of these systems are outside my immediate control (3rd party systems, done by other developers, etc). The overall real-time system is more like a system of systems. Because of this, I would like to somehow simplify their representation in my sequence diagram to focus on specific parts of the system.

I could create a Sequence Diagram with 26 lifelines that shows the flow between every component from A to Z and back again, but it seems like it would just clutter the diagram.

Is there a good way to simplify my UML in order to summarize the pieces that I am not interested in? There are a few reasons this might not be important, whether the message of interest never travels through them or other reasons. Or is UML the wrong tool and should I be using something different?

enderland
  • 12,091
  • 4
  • 51
  • 63
parrowdice
  • 193
  • 3
  • My question comment has been deleted, so I'll re-ask it in a slightly less incredulous way. Your question implies that you are trying to use UML to design a solution before coding. This is a really bad idea, unless you throw the UML away afterwards as it will result in badly designed code. Your code is your primary design document. So what are you trying to achieve with this sequence diagram? Is it up-front design, or just secondary documentation of the code? – David Arno Jul 15 '16 at 13:39
  • @DavidArno: "This is a really bad idea" - I'm surprised by that. I've done this for some time and it produces great systems / code (with minimal changes to the original design). Would you mind elaborating on the negatives of this approach, I'd be interested to hear your thoughts? The system I'm currently designing needs to interact with other systems that other people are currently designing. I'm creating an ICD (with sequence diagrams) so that the designers of the other systems can design their systems accordingly. – parrowdice Jul 15 '16 at 13:49
  • Do you control the layers you would be simplifying? It sounds like you want to simplify systems you are _not_ directly interested in exploring, in order to focus on a specific piece of the system (and not the entire system). – enderland Jul 15 '16 at 13:51
  • Whenever you write UML and expect someone to implement that, once you start writing code, you'll think of things that you didn't think of when writing UML. Part of that is just having more time to think, others are taking advantage of language features that you may not have thought of before you opened your code editor. You're left with needing to update models or throw away models. I think there is some use for UML (and modeling in general) before writing code to sketch out ideas, but it shouldn't be detailed. [Martin Fowler wrote about UML modes.](http://martinfowler.com/bliki/UmlMode.html) – Thomas Owens Jul 15 '16 at 13:53
  • @enderland: Yes, that is true to an extent. Various layers are third party, or made by other teams in my company. I do want to only focus on the areas of interest for the scenario that the sequence diagram aims to communicate, and not the entire system. – parrowdice Jul 15 '16 at 13:55
  • So why are you trying to use a sequence diagram? I think you're trying to use the wrong tools here. A sequence diagram tends to be at a high level of detail. For example, in your distributed system, a sequence diagram would likely only show the actions of a single node in the system, and not show a message as it propagates through the system across nodes. Deployment diagrams will show the nodes that are connected. And you aren't limited to UML - sometimes, just a few sentences to explain the diagrams are helpful, too. – Thomas Owens Jul 15 '16 at 13:57
  • I made an [edit] that I think clarifies your question and combines the information from comments and your edit. If that changed your intent too much feel free to [edit] and clarify - but I think it helps to make what you are looking for more clear. – enderland Jul 15 '16 at 14:01
  • @ThomasOwens: Hmm... Perhaps I could create a couple of sequence diagrams for the areas of interest, and then a deployment diagram for the rest. This seems like it would satisfy my needs. Does that sound reasonable? – parrowdice Jul 15 '16 at 14:08
  • @parrowdice, please have a read of http://programmers.stackexchange.com/questions/305093/why-is-it-inappropriate-to-use-uml-diagrams-to-plan-how-your-code-will-be-organi and my answer there. – David Arno Jul 15 '16 at 14:20
  • @parrowdice I think Thomas brings up a good point with the modes. We could better answer your question if we knew what you were making the diagram for. But regardless of if your mean it as sketch, blueprint, or language I still primarily want to know who your audience is. Some people diagram for themselves as they design a solution. Some diagram to communicate an idea they want verified by a colleague. Still others feel it is important to document what they have done for a maintenance programmer. What are you trying to do? – candied_orange Jul 16 '16 at 00:29
  • BTW, the "diagram for maintenance" idea is usually of limited benefit. As long as diagrams don't automatically generate code, and code doesn't automatically generate diagrams, code and diagrams will vary independently. – candied_orange Jul 16 '16 at 00:33

2 Answers2

3

Think about WHY you're making the sequence-diagram. Who your audience is and what they're going to get out of it.

UML is not always called for. If you're making it out of some sense of obligation to "design" step back and think for a minute. If it is simply tradition in your shop take a hard look at what people have done and ask how useful it is and why.

I've seen people create design diagrams that had to be the size of a conference table to print out large enough to read the text. These documents were good for a laugh but not much else.

I'm a big believer in one sheet of paper. I also believe in abstraction. While I'm tempted to say it's fine to lump a group of objects together on one lifeline if they are clearly labeled but I must ask, are you absolutely sure this isn't a sign of a problem with the design?

If it's hard to diagram on paper it's likely hard to navigate in code. Consider use of abstractions, facade pattern, and tell-don't-ask. None of these guarantees you can break it up into coherent individual single sheets of paper but they certainly help.

If you insist on staying with your current design you will have to find a reasonable way to depict it as is. In your case you have three components of interest out of 26. I recommend use of a cloud. Not the buzzword. The icon. Networking has long used a cloud icon to say "here we cross over a bunch of stuff we don't need to talk about now". Clearly label the cloud so it's clear where it begins and ends and you don't have to depict its internal components. You can give the cloud a lifeline and it'll fit right in.

That's not formal UML but if it communicates what you need it to, who cares?

candied_orange
  • 102,279
  • 24
  • 197
  • 315
0

You shouldn't be simplifying diagrams to the point where they no longer are reflective of reality. I think it's a good thing to focus diagrams on particular aspects of the system to improve clarity, but you don't want to have models that give people the wrong impression of your system. The best case scenario is that there is confusion when someone starts with your visualization and then looks at the implementation.

I think that your first step should be to narrow down the scope of your visual models. For example, if you want to show the overall topology of the distributed system, consider a deployment diagram, showing the nodes and pieces that go within each node and how they are connected. If you have a workflow, you can show the overall workflow in an activity diagram. When you want to crack open a node or one of the components that reside on the node, you can look at more detailed class diagrams for static structure and sequence diagram or timing diagram to show how methods are called within a particular node. You could use a communication diagram, or a modified form of a sequence diagram (if you aren't worried about sticking to formal UML), to show the top level messages that flow between nodes for a given operation.

If the subsystem is not in your immediate control, don't provide a highly detailed diagram showing how it will work. Instead, define the inputs and outputs using UML and other graphical or textual methods, but keep it high. Let the implementers create more detailed models.

In general, look at Martin Fowler's discussion of UML modes - keep it at the appropriate level of detail for your purposes. Also, look at the principles of Agile Modeling - maximize the ROI of your models, use multiple models where each model captures a specific aspect of your software, focus on producing working software over detailed models, and focus on communicating content (especially clearly and efficiently) rather than the representation of that content.

In this approach, you'll probably end up with more visual models, but each visual model will be smaller, which makes them easier to read and maintain (or decide to discard without losing other pieces of the picture).

Thomas Owens
  • 79,623
  • 18
  • 192
  • 283
  • Not sure why someone down-voted this as it's an excellent answer. "Your source code should be the one true representation of the design" is the key. – David Arno Jul 15 '16 at 13:36
  • 1
    This entirely misses the purpose the OP has in asking this question, which is simplifying component pieces of a large system of systems in order to focus on the relevant points of interest. – enderland Jul 15 '16 at 13:52
  • @enderland That information wasn't in the question when I posted this answer. I do need to edit. – Thomas Owens Jul 15 '16 at 13:54