Rule 9 – Build yourself a Data Dictionary
Transactions between the actors and the system typically involve the transfer of data. This data has to be defined somewhere. If you’ve built a Domain Model ( see Part 5 – here) most of the data will be identified there; but even then the class diagram is not always the most practical place to capture the sort of information you need to record.
Another way to capture this information is in a Data Dictionary. A data dictionary defines each piece of data in the system, and attributes about that data. Typically, a data dictionary holds (but is not limited to) the following:
- An Identifier. This is how the data will be referred to. Remember to use a term that has meaning in the problem domain.
- Definition. What does this data represent? (And remember: a good definition consists of a genus – what type of thing I’m defining – and a description)
- Units of measure; if applicable
- Valid range; again, if applicable
- Resolution. That is, what’s the smallest difference I can measure? This can become important if your implementation may use fixed point number schemes (for example).
This information is all vital to the developers who must design and code interfaces, etc. but it also has benefit when writing use case descriptions – it decouples the behaviour of the system from its data.
Just as we should decouple user interface details from the use case description (see Rule 8) so should we decouple the data transactions. Describing the data requirements of a transaction in the use case description is cumbersome and leads to a potential maintenance problem (what if the resolution of a data item changes? Or its units of measure? Ask the team that developed the flight systems software of the Mars Climate Orbiter about getting units of measure confused!)
As you define your data dictionary, you can refer to data items (by their name) in the use case text. Use some typographical convention (I use italics) to identify a data item from the data dictionary; or, you could hyperlink it.
If the data requirements change you shouldn’t need to change the use case – unless it leads to a change in behaviour. Similarly, you don’t need to elaborately detail exception flows for invalid data. The data dictionary defines what is valid; the use case defines what should happen if we receive invalid data. A simple, clear separation of responsibilities.
The Data Dictionary is not a new idea. Twenty years ago, when I started developing software, a Data Dictionary was always created, and was considered a vital part of the design. Unfortunately, it seems to have gone out of fashion, or been forgotten, in many software development circles.
He specialises in C++, UML, software modelling, Systems Engineering and process development.
- Practice makes perfect, part 3 – Idiomatic kata - February 27, 2020
- Practice makes perfect, part 2– foundation kata - February 13, 2020
- Practice makes perfect, part 1 – Code kata - January 30, 2020
Glennan is an embedded systems and software engineer with over 20 years experience, mostly in high-integrity systems for the defence and aerospace industry.
He specialises in C++, UML, software modelling, Systems Engineering and process development.
