Skip to content

Good bait catches fine fish – part 2: How to write a specification for developers

In my recent blog we saw, how a specification for customers can look like. A specification needs to fulfill many different requirements and at the same time it has to be understood by the customer, testers, and of course also the developer.

Which information do developers need?

Developers want to know what they have to implement. Usually they want to develop a pretty solution. “Pretty solution” doesn’t mean a nicely designed user interface at all. It means moreover, easily readable code and easily comprehensible implementations.

An easily comprehensible code is created, when single components don’t have heavy dependencies. And if dependencies are necessary, they are coded explicitly as interfaces. In such a way it is easy to understand what the code is about and even to fix bugs, even when someone has not written the code himself.

In the following sample, an item is added to an invoice – first almost not readable even for programmers and second readable (almost) even for non-programmers. 

Specification for Developers Specification for developersThose both samples are doing the same 🙂 . But in the first sample, someone cannot recognize what the code is about. On the other hand, it is clear what should happen in the second sample (even though someone wouldn’t have the comments).

domain model for software specificationHowever, clear code is a goal of developer, but there is no connection to a specification. Unfortunately it is! The terms, which appear in the code — in our sample invoice and item — we have to define out of business perspective in the specification. We can select different ways to do so — or we can even combine them.

A glossary is helpful in every case and shouldn’t be missed in any specification. But it can become quite long and the dependencies and combinations of the business objects are lost.

Therefore it is recommended, to model the business objects appearing in our specification in a domain model. The domain model contains a graphical model which explains the systematic and the dependencies of the business objects – but that alone is not enough. The business objects need to be defined — using natural language.The picture above shows an example of a domain model.

Here you can find out how to write a specification for testers.

read more from