Analysis, design, and never the twain shall meet

So, how to get from analysis to design in a few easy steps. Here goes:

First, create a domain model. This is a glossary of real-world terms used in the project. Some excellent books have been written on domain modeling, most notably Domain-Driven Design by Eric Evans. Your initial attempt at the domain model shouldn’t take very long; a couple of hours at most. You just want a rough draft, from which you can write the use cases.

Second, write said use cases – and – (this is important) reference the domain objects in the use case text. Use cases are behavioural requirements: they define how the user and the system will interact, and are written in user action/system response couplets:

“The user enters his username and password and clicks Login;
the system validates the login credentials
from the Master Account List
and logs the user in.”

It isn’t exactly Shakespeare, but it’s clear and unambiguous. Use cases, when written properly at least, are divided into one basic course and many alternate courses (aka sunny day and rainy day scenarios). You’d want to describe what happens if the user entered the wrong password, for example, so this would go in an alternate course.

Third, and this is the lynchpin, do some preliminary design. This is really the bridge that gets you from analysis (use cases) to detailed design. The goal of this step is to bash your use cases into shape, so that you can do good stuff with them such as create an object-oriented design, produce accurate estimates, and write meaningful unit tests.

Such a lot of advice has been written about how to write use cases, and most of it is contradictory. Depressingly often, I hear people being told to write “high-level” use cases: that is, make them vague and technology-independent. Trouble is, if you hand a vague and technology-independent use case to a programmer, you’ll end up with a fuzzy design that is ambiguous, buggy, and full of undiscovered functionality. And this is where our hero programmer comes into play: he’s coding away, and is the first to discover that the requirements spec is missing some crucial “what-ifs”. He’s on a roll and doesn’t want to stop, so he hacks in whatever’s convenient from a programming point of view. This entire dysfunctional situation can be avoided by doing preliminary design while you’re still writing the use cases.