Skip to content
Software Architecture Guide

UML Modeling Anti-Pattern

Explanation

Section titled “Explanation”

Some diagrams present themselves as UML (the Unified Modeling Language, a standard drawing notation) but use notation the author never explained. Readers cannot tell what the symbols mean.

Unexplained boxes, lines and numbers. Boxes and lines have no built-in meaning. Without an explanation, readers interpret them differently from the author’s intent. Informal sketches often leave the meaning of different box and line styles unexplained. This is a common flaw.

Arrows need a defined meaning. Follow the standard UML meaning, or explain the arrow in a legend. A legend is a small key on the diagram that says what each symbol means. A non-standard notation needs one. Line labels should match the direction and intent of the relationship. Vague labels like “Uses” do not help. See UML Association and UML Class Diagram Relationship for the standard meanings.

One diagram, one purpose. A diagram that mixes several kinds of elements leaves readers unsure what it shows. A title naming the diagram type and scope supports one purpose per diagram. See Differences between Class, Component and Package Diagrams.

Strict UML or informal sketch? Both can work. UML is tool-supported, has clear semantics and is standardized. It is optional, though, and gives no guaranteed benefit. Informal sketches can communicate well, provided they carry a legend. UML sketches are often selective, and communication matters more than obeying every rule. What matters is that all stakeholders understand the notation the same way. Choose diagrams and notation deliberately, reflecting project and company culture.

Relation to C4. C4 asks for a key on every diagram, whichever notation you pick. It also offers a short review checklist, and each diagram should stand alone without a narrative. C4 diagrams can also be drawn in UML, using packages, components and stereotypes. The UML version tends to carry less descriptive text.

Example

Section titled “Example”

A team draws one picture with numbered arrows, some boxes that look like deployed servers, and some that look like code packages. Nobody explains the numbers. One reader sees a call order, another sees priorities. The team fixes it by splitting the picture into two titled diagrams. Each has a legend. Arrows get labels that state what flows and in which direction.

Trade-offs

Section titled “Trade-offs”

Strict UML gives clear, standardized meaning and tool support. It can take more effort and does not guarantee benefit. Informal sketches are quick and selective. They depend on a legend to avoid misreading. Which to use depends on the audience and on project and company culture.

Checks

Section titled “Checks”
  • Every diagram has a legend that explains any notation that is not standard.
  • Every relationship line is labeled, and the label matches its direction and intent.
  • Each diagram has a title naming its type and scope.
  • The notation choice is deliberate, and stakeholders share one understanding of it.
  • Each diagram can be understood without a separate narrative.
Section titled “Related”

Sources

Section titled “Sources”