UML Class Diagrams: A Complete Practical Guide
The class diagram is the most useful diagram in UML. This guide covers everything on the box, every line between boxes, and how to draw one that clarifies rather than clutters.
If you draw one UML diagram in your career, it will be a class diagram. It is the map of an object-oriented system: the classes that make it up, the data they hold, the operations they offer, and the relationships that bind them together. Read fluently, a good class diagram tells you how a codebase is shaped before you open a single file, which is why it is the first thing many engineers sketch when they inherit unfamiliar code.
The notation looks intimidating because there are a lot of line styles, but the underlying ideas are simple and worth learning properly. This guide walks through the anatomy of a class, the visibility and multiplicity markers, and the five relationship types you actually need. You can follow along in the editor at /diagrams, and the reference at /diagram-tools/uml-diagram has additional examples.
Anatomy of a class box
A class is drawn as a rectangle divided into three horizontal compartments. The top holds the class name, in bold and centered. The middle lists attributes: the data each instance holds. The bottom lists operations, the methods the class exposes. For a quick sketch you can collapse the lower compartments and show only the name, which is often all a high-level diagram needs.
Attributes and operations carry a visibility marker: a plus sign for public, a minus for private, a hash for protected, and a tilde for package-level. A typical attribute line reads "- balance: Decimal" meaning a private attribute named balance of type Decimal. An operation reads "+ withdraw(amount: Decimal): boolean", a public method taking a Decimal and returning a boolean. Underlining an attribute or operation marks it as static, belonging to the class rather than an instance.
The five relationships that matter
The lines between classes carry as much meaning as the boxes. Getting them right is what separates a diagram that documents a design from one that misleads. There are five you need in daily practice, and they form a rough spectrum from loosest to tightest coupling.
- Association. A plain solid line meaning two classes are related and one holds a reference to the other, for example an Order associated with a Customer.
- Aggregation. A solid line with a hollow diamond at the "whole" end: a has-a relationship where the part can exist independently, like a Team and its Players.
- Composition. A solid line with a filled diamond: a stronger has-a where the part cannot exist without the whole, like an Invoice and its LineItems.
- Inheritance (generalization). A solid line with a hollow triangle arrowhead pointing at the parent: a SavingsAccount is-a Account.
- Realization. A dashed line with a hollow triangle: a class implements an interface, like PaymentGateway realizing IPayable.
- Dependency. A dashed line with an open arrowhead: a transient uses-a relationship, such as a class that takes another as a method parameter.
Multiplicity: how many of each
Numbers near the ends of an association line state how many instances participate, and they are one of the highest-value annotations you can add. A "1" near Customer and a "*" near Order on an association means one customer has many orders. Common multiplicities are 1 (exactly one), 0..1 (optional), * or 0..* (zero or more), and 1..* (one or more). You can also give exact ranges like 2..4.
Multiplicity is where a class diagram stops being decorative and starts encoding real design decisions. Whether an Order can have zero line items or must have at least one, whether an Employee reports to exactly one manager or optionally none, are the kinds of rules that cause bugs when they are ambiguous. Writing them on the diagram forces the conversation early, which is exactly when it is cheap to have.
A worked example
Consider a small e-commerce model. A Customer class has private attributes for name and email and a public method placeOrder. An Order class has an orderDate and a status, and a composition relationship to LineItem with multiplicity 1..* because an order without line items is meaningless. Each LineItem has an association to Product with multiplicity 1, and a quantity attribute. A Customer has a one-to-many association to Order. Already this tiny diagram encodes several real rules a developer would otherwise have to infer from the code.
Notice what the diagram deliberately leaves out: there is no mention of the database, no getters and setters cluttering the operations list, no utility classes. That restraint is the skill. If you want to generate a first draft of a model like this from a description, the AI generator at /diagram-tools/ai-diagram-generator will produce the boxes and lines from a plain-English prompt, and you refine the relationships and multiplicities by hand.
Common mistakes to avoid
The most frequent error is confusing aggregation and composition, or using a diamond when a plain association would do. When in doubt, use a plain association; the diamonds carry a strong lifecycle claim that is often not what you mean. The second common error is drawing every class in the system, which produces a wall of boxes nobody reads. Scope each diagram to a subsystem or a single question.
The third mistake is treating the diagram as a permanent artifact that must match the code forever. Class diagrams drift the moment you refactor. Draw them to think and to communicate, keep the durable ones close to the code so they are easy to update, and let the throwaway ones be thrown away. You can sketch and export these quickly from /diagrams in whatever format your docs need.