Are there any good resources discussing the creation and use of UML component diagrams?

Question

As part of an assignment, I have to create a component diagram for existing code. I understand what a component diagram is and the information it presents, but I'm not sure of a process to follow when looking at code to diagram it out to produce a component diagram. I'm also not sold on how a component diagram, if I am presented with one, would help me with implementation of a system.

Answer 1

For me UML isn't primarily about helping me to design a system (though it does help). It's about helping me to communicate the design to others by giving us a common language/notation.

It makes the conversation easier so we don't waste time trying to translate between our different frames of reference.

Answer 2

Maybe have a look at Scott Ambler's UML 2 Component Diagramming Guidelines and Introduction to UML 2 Component Diagrams. These are IMHO two good resources that explain how and when such diagram can be used.

Answer 3

You state two separate concerns: how to get from code to diagram, and how to use one as a guide to implementing a system. If you're diagramming existing code, I don't think the second question applies.

If you're designing new code, then a component diagram can be 1) a useful abstraction to understanding the important parts of the code, minus all the distractions, and 2) a good way to communicate to others.

If you're looking at existing code, then an existing component diagram (or one of several other UML artifacts) can be a guide to the code, which especially helps in maintenance: it can be easier to identify the location of bugs, major class responsibilities, etc.

If there's no diagram, then the exercise of making one by reading code is a good way to familiarize yourself. I've done this in a number of cases when inheriting a complex codebase. As a result, I have a couple of pages of diagrams of the application and database that tell me at a glance the interesting things about its major components. At any given time, I'll be very familiar with some areas and not others, depending on what I'm working on. The diagrams are a good reminder of how to use various parts of the application. And they're helpful when bringing others onto the team; they understand the code much faster after a half-hour walk through the diagram.

To work from existing code, you'll need to read through it, identify the major classes in use, and trace back to understand the dependencies and the interfaces, method signatures and data structures they use to collaborate. If it's a database-backed app, it can be helpful to see a description of the DB, as it should embody the main concerns of the application.

It helps to have some use cases to guide the investigation, since with event-driven applications you need to understand what the user is doing in order to trace through the code. If there are no existing use cases, then start by writing some simple high-level ones yourself. Then go through the code by use case, and identify the major objects in use. Hopefully, you'll find major classes in the program to macth the major use cases you identify. E.g., if the application is a web-based e-commerce app with an administrative user-interface, then you'll identify a number of end-user and administrative-user use cases, and should expect to see some classes specific to each of those families, as well as generic and utility classes used throughout.

Stay at a high level, avoid the temptation to account for every single thing you encounter.

As Pascal said, Scott Ambler's a great resource of practical UML knowledge, and has guildelines that can be used as little or as much as necessary. Specifically, see Introduction to UML 2 Component Diagrams. Hoever, he's writing much more for people designing new code than those documenting existing code, so you have to adapt some of what he discusses.

Answer 4

Martin Fowler's "UML Distilled" is still the best book on UML you can get. Its chief virtue is that it's thin - densely packed with info.

Answer 5

• The Scott Ambler is another good off-the-shelf standard answer. However, in the case of component diagrams I find the suggestions under (Section Creating Component Diagrams) fine, but long and not relevant to your documentation needs. From Scott's list (Creating Component Diagrams) I would really focus on just (1, 4, 5, 13), as many of the suggestions are design best practices. I will add some more of my own below.

• Martin Fowler's book is great in many ways, but not really in depth for Component Diagrams or Co.. A massive 7 pages, which shows you where it was prioritized during his writing, as class diagrams get 18 pages or so.

• I agree with you that you should be able to realize when to use a UML diagram. The UML 2.2 Specification itself says that it was built for Component (Service/Interface) Oriented systems. Taking a basic MVC GUI app and pushing into a Component diagram/model really does not make sense. There are also a couple ways of diagramming the component relationships, Scott Ambler's site shows them in Figure 1. For large multi system implementations I have found these diagrams very effective, e.g. lots of interfaces and lots of abstraction of systems.

My Suggestions: (I use components for modeling often, and I read the UML spec on this stuff)

• Skip using ports for the HL component diagram, they are for grouping and although they look fun in Scott Ambler's diagramming you do not gain a lot for the effort.

• Avoid getting caught up in an internal Component Structure. Only do this if clarity is needed for a high level of complexity.

• Don't slip into making most "classes" into components.

• Focus on the interfaces and where real boundaries exist, clues are public interfaces, package groupings, WSDL, external system interactions.

• For your first several I would start top down. First make one of all the external system interactions, then do the next level down, use ports and composite structure if you want, but I don't like them, they are messy because the composite structure are actually Parts, a UML object that is an instance of a class or component, the naming get complex etc.

• Pick one notation in general, use the ball and socket connections for tight coupling and only switch to the use/depends line between component and provider for loose coupling where there component (interface realizations) can actually be switched, both are mixed in Scott Ambler's figure 1 (linked above), loose on the left and tight coupling on the right. The UML spec also mentions this in section 8 of the UML 2.2 Superstructure.

Answer 6

From the following topic in the VS 2010 Ultimate docs:

UML Component Diagrams: Guidelines: http://msdn.microsoft.com/en-us/library/dd409393%28VS.100%29.aspx

Drawing component diagrams has several benefits:

Thinking of your design with regard to the major blocks helps the development team to understand an existing design and create a new one.

By thinking of your system as a collection of components with well-defined provided and required interfaces, you improve the separation between the components. This in turn makes the design easier to understand and easier to change when requirements change.