Names and titles

Names are the text that identifies a shape: a component’s or state’s name, a package’s name in its tab, the name beside an entry point. The diagram title is a caption.

Centre a classifier’s name, keyword above

Rule. A component, class, interface or other classifier shows its name centred in bold, with any keyword or stereotype centred in plain text above it, in guillemets. This includes a composite component, whose name is centred in its header.

Why. UML asks for it, and a centred name marks the box as one unit.

Source. UML 2.5.1, 9.2.4.1, p. 101: “The name of the Classifier should be centered in boldface”, with keywords “centered in plain face within guillemets above the Classifier name”.

Status: enforced in component and package diagrams. See DECISIONS.md, “UML 2.5.1 audit”.

Put a package’s name in its tab when it shows its contents

Rule. A package that shows its members carries its name, left-aligned, in the tab. A package without visible contents has a blank tab and its name in the body.

Why. UML specifies both cases. Readers find the name in the same place in every package.

diagram package "Names in tabs"

package Core {
  class Order
  class Invoice
}
package Util
Core ..> Util : <<import>>

Source. UML 2.5.1, 12.2.4, p. 248.

Status: enforced, in package diagrams and for packages inside component diagrams.

Keep lines off names

Rule. No line crosses a name, a keyword, a composite state’s internal activities, or a package tab.

Why. A line through text hides both. A line through a tab reads as entering the tab, which means nothing.

Bad: the arrow pierces Util’s tab to reach the body below it.

Source. Keep lines out of shapes and names.

Status: enforced. Composite names, state headers and tabs are obstacles for every line that enters their container. The study found that, as obstacles, they cost no bend in any golden file.

Let arrows end on a package’s tab

Rule. A relation arriving at a package from above may end on the top of the tab, when that is where its straight line meets the package.

Why. The tab is part of the package symbol, so a line ending there points at the package. If the top side started right of the tab, a line that would arrive over the tab would jog sideways instead.

Source. UML 2.5.1, 12.2.4, p. 248 (the tab is part of the symbol); Layout levers.

Status: enforced for packages without visible contents, whose tab is blank (tab_takes_ends in the package routing). An end on the tab stays 8px from its corners and 16px from the step down to the body. It saved 8 bends in the golden files, in language-relations, language-cycle and gallery-merge. A package showing its contents keeps its name in the tab, so its top side still starts right of the tab.

Let a name give way to a line

Rule. Where the notation leaves the name’s position free, move the name aside instead of bending a line. A composite state’s name may sit left or right in its name compartment, or in a UML name tab, when an entry point or a straight line wants the middle. A classifier’s name stays centred, because 9.2.4.1 asks for it.

Why. The name can move without loss. The line cannot bend without cost. Today an entry point slides off the centred name instead, and the transition into it then jogs.

Source. UML 2.5.1, 14.2.4.4, p. 319-320, which allows an optional name tab “resting on the outside of the top side of a State”; Layout levers.

Status: planned. Small gain: 2 of the 11 composite state names in the golden files would move, saving 4 bends.

Keep connection point names beside their symbols

Rule. An entry or exit point’s name sits next to its circle, clear of the state’s own name, and the entry point itself slides along the border off that name.

Why. Two names overlapping cannot be read, and a connection point name far from its circle is easily taken for the state’s.

Source. UML 2.5.1, 14.2.4.6, p. 327-328 (entry and exit points as circles on the border, “with the name associated with it”).

Status: enforced (clear_of_name in the state layout).

Caption the diagram, do not frame it

Rule. A diagram kind "Title" title is a caption above the drawing, outside its contents area. There is no UML frame.

Why. A frame adds a box around every drawing and competes with the content. UML makes the frame optional, and drops its heading with it.

Source. UML 2.5.1, Annex A; DECISIONS.md, “Frames, gates and coregions stay undrawn”.

Status: enforced, by core::svg::document.