Skip to main content

Beyond TDD: Documentation Driven Development

There are quite a few articles extolling the virtues of test-driven development these days (here's one). And for good reason, too. Having done TDD for quite a while, I recently started combining it with documentation-driven design. This is what my open-source tool, JCite, is all about.

With this approach, I
  • sketch out the most important use cases,
  • combine them into the index of a tutorial (links plus teasers summarizing the use-case),
  • flesh out the tutorial topics (and thus use-cases) one by one,
  • develop the use-case tests in parallel to each topic,
  • cite the important parts of the tests as actual code samples into the topic, and
  • only then start doing the implementation (this last step is accompanied by more tests, which are now more like unit-tests).
In all, this is like literate programming, but of the use-case tests rather than the implementation code.

TDD already helps to make you focus on the user during API design. DDD takes the effect further by making you tell consistent and convincing stories for each important use-case to your users. This uncovers things like
  • inconsistent or poor naming: its easy to live with a poor name in a test - but hard to explain it,
  • overly complex design: you, the designer, have the design fully present in your mind, it often does not really seem complex when you write the tests - but try writing down all the details of why it is how it is: it will quickly make you wish it was simpler - and remember: your story should be convincing,
  • the need for simplified APIs atop more complex and powerful lower-level APIs: if you have to explain the same setup code over and over again, you'll see the need for a simplified API for typical setups, and
  • feature creep: features and options you don't really need, but thought you might just add quickly, become more expensive because every feature now incurs the full cost of documentation, test, design and implementation.
And it ensures that when you release, you always release a fully documented product. What good is a feature no one knows about?

(See RSpec and BDD - something crucial missing? for more of my thoughts on this.)


Popular posts from this blog

Threaded chat article and demo

While nothing major, managing threaded conversations in chat has bothered me for quite a while. Yesterday I had an idea on how to improve matters:
Works using existing chat infrastructure. Needs only augmented clients.Plays well even if other party uses a non-thread aware chat tool.Separates threads automatically based on interaction patterns.I've written an article and have created an online demo about it. Discussion welcome.

Access 2003 and the DCOM Server Process Launcher

Here's a hint: Don't disable the "DCOM Server Process Launcher" service on XP SP2. It may look like one heck of a vulnerability when you really don't use DCOM at all, but, unfortunately, Microsoft Access 2003 does. It will simply open an instant message box stating "A problem occurred while Microsoft Access was communicating with the OLE server or ActiveX Control." if the service is not running.