The most successful and fun project I have been part of developed a network simulator for operator training. We had a great team and freedom to work how we wanted, but another key to success was the domain model. The analyst drew object diagrams to explain to the programmers and testers how a network topology could be, for instance like this:
This may look simple, but these diagrams explained a lot to us. We used them to discuss what should happen in different scenarios, such as what should happen when a Trunk is connected to another Port. Then we implemented these scenarios as unit tests. This resulted in a robust implementation with few bugs.
But in most projects, we don't have anything like this. In one project I spent several days trying to understand how a trading system worked. I had the domain model and database schema, but it was not clear when these objects were created, updated and deleted in the database. I read thousands of lines of code and run the program in a debugger, but this didn't tell me when the behavior was executed. Finally, I found out, and I drew some diagrams. When I presented this to the project manager, analyst, testers and other developers, it was a revelation to people that had worked on that system for years. They finally understood the internal behavior of their application. This behavior was certainly clear to the original designers of the application, but it was not documented anywhere. The result was that new programmers like myself struggled to understand the application logic. This happens all the time in our industry. It is frustrating for developers and costly for companies.
Developers need some documentation; the code is not enough. But what is the best format for this documentation? We don't need thick Word documents. A few examples of domain objects can take us very far. And the great thing about domain objects is that they can be discussed with users, analysts and testers, so that the whole team get a shared understanding of the behavior of the application.
We can take a few key examples of the system behavior and show which domain objects are needed in those examples and which objects are created, deleted and updated. This gives a high-level view of the internal behavior of the application.
The example below shows one way to do this.
Given the following objects: 
When the user enters the following: 
Then the application should give the following output:
And the following objects should be created:
Examples connected to domain objects give a high-level view of what the application is doing. It is suitable for discussions with users, analysts, developers and testers, and it is great documentation for future developers.
The example is ready to test and the format is well suited for test automation. By using this specification as input to a test automation tool, you get high-quality tests that focus on the domain logic instead of brittle user interface testing. This kind of tests are great input to programmers, because they are directly connected to the specification and they contain the details that the programmers need. (I have written about specification by example here.)
In the example above, I used the terms Given, When and Then to show how this method can be compared to Behavior Driven Development (BDD). The difference is that BDD uses 3 steps (Given, When and Then), while this method uses 4: Initial objects, Input, Output and Result objects. More importantly, the present method uses domain objects more explicitly than BDD. This gives a strong connection between the specification (examples) and the object model. When this is combined with automatic tests, the specification, code and tests will be tightly integrated and kept consistent with each other. The domain objects become the glue that binds everything together. 
This may look simple, but these diagrams explained a lot to us. We used them to discuss what should happen in different scenarios, such as what should happen when a Trunk is connected to another Port. Then we implemented these scenarios as unit tests. This resulted in a robust implementation with few bugs.
But in most projects, we don't have anything like this. In one project I spent several days trying to understand how a trading system worked. I had the domain model and database schema, but it was not clear when these objects were created, updated and deleted in the database. I read thousands of lines of code and run the program in a debugger, but this didn't tell me when the behavior was executed. Finally, I found out, and I drew some diagrams. When I presented this to the project manager, analyst, testers and other developers, it was a revelation to people that had worked on that system for years. They finally understood the internal behavior of their application. This behavior was certainly clear to the original designers of the application, but it was not documented anywhere. The result was that new programmers like myself struggled to understand the application logic. This happens all the time in our industry. It is frustrating for developers and costly for companies.
Developers need some documentation; the code is not enough. But what is the best format for this documentation? We don't need thick Word documents. A few examples of domain objects can take us very far. And the great thing about domain objects is that they can be discussed with users, analysts and testers, so that the whole team get a shared understanding of the behavior of the application.
We can take a few key examples of the system behavior and show which domain objects are needed in those examples and which objects are created, deleted and updated. This gives a high-level view of the internal behavior of the application.
The example below shows one way to do this.
Given the following objects: 
When the user enters the following: 
Then the application should give the following output:
- Total hours: 39
And the following objects should be created:
Examples connected to domain objects give a high-level view of what the application is doing. It is suitable for discussions with users, analysts, developers and testers, and it is great documentation for future developers.
The example is ready to test and the format is well suited for test automation. By using this specification as input to a test automation tool, you get high-quality tests that focus on the domain logic instead of brittle user interface testing. This kind of tests are great input to programmers, because they are directly connected to the specification and they contain the details that the programmers need. (I have written about specification by example here.)
In the example above, I used the terms Given, When and Then to show how this method can be compared to Behavior Driven Development (BDD). The difference is that BDD uses 3 steps (Given, When and Then), while this method uses 4: Initial objects, Input, Output and Result objects. More importantly, the present method uses domain objects more explicitly than BDD. This gives a strong connection between the specification (examples) and the object model. When this is combined with automatic tests, the specification, code and tests will be tightly integrated and kept consistent with each other. The domain objects become the glue that binds everything together. 
Comments