The Complete UML Set

Every source is in the repository under docs/uml, and every figure is redrawn from its source by one command (Chapter 19).

The seven checks, run

Checks 5 and 7, and the agreement of the model with the code, are made by two short scripts in the book's tools rather than by eye, and they report:

schema: 5 tables, 30 columns: er.puml and schema.sql agree column for column (names, order, types, keys, NOT NULL)
model: 5 classes, 22 attributes all stored; 3 enumerations match the schema; the state machine's 6 states and 5 moves match Status and rules.js

The first compares the ER diagram with the schema. The second checks that every attribute of every class is a column of its table, that each enumeration has exactly the values its column allows, and that the state machine's states are the Status values and its arrows exactly the moves the code allows. Each script tests itself first: it plants mistakes, a changed type, a missing column, an extra status, a redrawn arrow, and stops if it misses one, so its "agree" can be trusted. Your team can make the same checks by hand, with a printout and a pencil, and should, every time a diagram changes.

The drafts did not pass, and each mistake is told in its diagram's own chapter. Before the design review, the checks found a class called OrderLine while its table was order_items, three attributes missing from the class diagram (Chapter 19), and a deployment diagram that claimed HTTPS the trial cannot have (Chapter 25); all were corrected in version 1.0. Other mistakes survived the review. Once the ordering code existed, comparing the diagrams with it found a sequence diagram that saved an order after rolling it back, with no refusal for a second order in the same slot (Chapter 22), and an ordering diagram that checked the stock and then took it, beside a serving diagram with no kitchen (Chapter 23). Those corrections are version 1.1.

Two lessons follow. Checks made by eye miss things, which is why two of them are worth scripting. And a design is checked again once the code exists: the diagrams describe the system, so when the two disagree, one of them is wrong and must be put right. A set that has never failed its checks has probably never been checked.

The design column

Chapter 9 began the traceability matrix with each requirement's source, and the SRS added its use case. The UML set adds where each requirement is realised in the design, with the figure numbers of the list above:

Every requirement has a design element and an API route. And every route in the API table of Chapter 30 names the requirement it serves, except the two that serve the system itself: who is signed in, and whether the server is up. Module 2 adds the last column, the tests (Chapters 54 and 55).

The problems a guide sends back

• Diagrams that disagree with each other or with the SRS, found in a minute by comparing names.
• A missing kind: no deployment diagram, or an ER diagram presented as the class diagram.
• Unreadable diagrams: forty use cases on one page, or a sequence diagram shrunk to fit.
• Diagrams with no number, caption or explanation.
• Diagrams that belong to a different system: a textbook's library example with the names changed.
• No link to the requirements, so nobody can tell what each diagram is for.

Do this for your project

1. List the diagrams your system needs: MU's six kinds at least, several of a kind where needed, and any other kind that says something better.
2. Number and caption every diagram, and write what it shows and which requirements it realises.
3. Run the seven checks, and fix every disagreement before the design review.
4. Add the design column to your traceability matrix.
5. Keep every source in your repository, and redraw every figure from its source before submitting.

Mistakes that cost marks

Six diagrams, one of each, and nothing else, when a use case with a transaction needed its own sequence diagram.

A set assembled the night before, with no cross-check, so the class diagram and the ER diagram name different things.

A traceability matrix with no design column.

Pictures pasted from different tools at different sizes, with no common numbering.

Quick revision

• Complete = nothing missing, nothing unexplained, nothing contradictory.
• The set: title page, version history, list of figures, one section per diagram (figure, caption, text, requirements realised, source), the cross-check, the design column.
• The seven checks of Chapter 19, run and recorded; some can be made by a script.
• The design column: for each requirement, the figures, classes, tables and API routes that realise it.

Questions you must be able to answer

1. What makes a UML set complete? It has every kind of diagram the system needs, at least MU's six and any others that say something better; every diagram is numbered, captioned, explained and tied to the requirements it realises; and the diagrams agree with each other and with the SRS.

2. How can you check that a class diagram and an ER diagram agree? Attribute by attribute: every attribute of every stored class must be a column of its table, by one stated naming rule such as camelCase to snake_case, with any exception written down, and each enumeration must have exactly the values its column allows. It can be done by hand with a printout, or by a short script, as this chapter's two are, which compare the files themselves and test themselves by planting mistakes they must catch.

3. What is the design column of a traceability matrix? The column that names, for each requirement, the parts of the design that realise it: its diagrams, classes, tables and API routes. It shows that every requirement is designed for, and that no design element exists without a requirement.

4. Why did the worked team draw a state machine when MU does not list one? Because FR-15's rule, which status may follow which, is exactly what a state machine shows; and because the diagram can then be checked against the database and the code: its states are exactly the statuses the database allows, and its arrows exactly the moves the code allows.

5. Name three problems a guide commonly sends back in a UML set. Diagrams that disagree with each other or with the SRS; diagrams with no number, caption or explanation; and unreadable diagrams, such as one crowded use case diagram where two readable ones were needed.