Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 39 ยท Modeling Practice

Model Review and Common Mistakes

Review UML models like code: a checklist per diagram, the most common mistakes with fixes, and a runnable model linter that finds naming and consistency problems.

Diagrams are easy to draw and easy to draw badly. Unlike code, a diagram has no compiler: nothing stops you from creating a class with no operations, a state with no exit or a sequence diagram that calls a method that does not exist. Quality comes from review. This lesson gives you a checklist for each diagram type, the mistakes you will see most often, and a small linter that automates part of the job.

What good looks like

A good diagram:

  1. Answers one question for one audience, and says so in its title.
  2. Has a readable size: roughly 5 to 9 main elements, rarely more than 15.
  3. Uses consistent names and notation, matching the domain's words.
  4. Shows only the detail needed for its level of abstraction.
  5. Agrees with the other diagrams and with the code.
  6. Has a legend if it uses stereotypes or colors.

If a diagram needs a long explanation, it is probably two diagrams.

Review checklist by diagram

Class diagrams

  • Names are singular nouns, written in the domain vocabulary; operations are verbs.
  • Every association has multiplicity at both ends; a role name where it is not obvious.
  • Composition only where parts really die with the whole.
  • No class without a clear responsibility ("Manager", "Helper", "Data" are smells).
  • Inheritance means is-a in behavior, not only shared attributes (Liskov).

Sequence diagrams

  • One scenario per diagram, with a title naming it.
  • Each message matches an operation of the receiving class.
  • Activation bars (when drawn) are balanced; return messages are shown where they matter.
  • Error and alternative paths use alt or separate diagrams, not silent assumptions.

State machine diagrams

  • Exactly one initial state; a final state only if the object really ends.
  • No dead ends (a state with no exit) and no unreachable states.
  • Guards on the same event are mutually exclusive.
  • Every event of the diagram exists as an operation or signal.

Component and deployment diagrams

  • Every required interface has a provider.
  • No dependency cycles; arrows point toward stable parts.
  • Every protocol on a link is named; replicas and single points of failure are visible.

Use case and activity diagrams

  • Use case names are verb phrases from the actor's perspective ("Place order").
  • Use cases describe goals, not steps; steps belong in activity or sequence diagrams.
  • Activity diagrams have a start, an end, balanced forks and joins, and guards on every decision branch.

The most common mistakes

Mistake Why it hurts Fix
The "god diagram" with 60 classes Nobody reads it Split by subject; show one neighbourhood per diagram
Attributes that are really associations (customer: Customer inside Order and also an arrow) The same fact is drawn twice Use the association only
Arrows without meaning (plain lines everywhere) Readers guess Use the specific relationship and add multiplicity
Aggregation everywhere The diamond adds nothing Use plain association unless ownership matters, composition when it does
Inheritance for reuse only Breaks substitutability Prefer composition
Modeling the database instead of the domain Mixes levels Keep a domain model; model tables separately
Use cases as steps ("Click button") Too low level Keep goals; move steps to scenarios
Technology in the conceptual model (HashMap, Controller) Hides the business meaning Keep conceptual diagrams technology-free
Diagram drawn once and never updated Misleads Generate structural diagrams or review them in pull requests
Missing legend and title Reader cannot tell what is shown Always add both

Review as a team

A 20-minute review catches most issues:

  1. The author walks through one scenario across the diagrams (a use case, the sequence, the class operations used).
  2. Reviewers look for missing things: error paths, states, constraints.
  3. Record decisions and open questions next to the diagram.
  4. Put diagrams under version control as text (Mermaid, PlantUML) so changes appear in pull requests.

Text-based diagrams are especially helpful: a diff shows exactly which relationship changed.

A model linter

Some rules are mechanical, so a script can check them. The example below applies four rules to a tiny model: naming, empty classes, missing multiplicity and dependency cycles.

Python Lint a class model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Checking consistency between diagrams

Cross-diagram checks are where tools beat people. Here, messages of a sequence diagram are compared with the operations in the class model.

Python Find messages without an operation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Both missing items are real design decisions waiting to be made: does the cart own checkout, or does a new Checkout class? Is there a Mailer component? The review has found a gap before the code did.

When to stop modeling

Stop when the diagram answers its question for its audience and the team agrees on what to build. More detail rarely helps. If you notice that you are updating a diagram more than you are using it, reduce it or generate it from code.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which is a typical sign that a diagram should be split?

    A diagram should answer one question for one audience; large ones are rarely read.
  2. 2. A state with no outgoing transition that is not a final state is:

    Dead ends trap the object forever unless that is intended.
  3. 3. Which use case name follows good practice?

    Use cases are verb phrases that state a goal from the actor's perspective.
  4. 4. Why keep text-based diagrams in version control?

    Reviewable, versioned diagrams are less likely to go stale.

Summary

  • Review diagrams like code: one question, one audience, readable size, consistent with other views.
  • Use a per-diagram checklist and watch for the common mistakes: god diagrams, vague names, misused diamonds.
  • Walk one scenario through all diagrams in a short team review.
  • Automate mechanical rules and cross-diagram consistency with scripts or tools.
  • Stop when the diagram has done its job.

Next: Project: Library System Model