- The epistomology thread was nifty, but it departed from the issue
that seems more crucial: Are (test) documents useful or a waste of
time? When is a document a better "transport" than a conversation?
The XP hard line -- avoid documents, just talk -- is what I think
I'm hearing from Ron.
For me, this is an area where XP has overreacted. I definitely see a
place for (non-code) documents in an agile process. The essential
work of a sw development project is building knowledge, plus sharing
and distributing the knowledge effectively among all of the people
involved. (Subsequent to this, the application of that knowledge by
any individual is *relatively* straight-forward.) Documents work
because you can use them early (models that build knowledge),
because they persist (you're not crippled by your imperfect memory),
because they're efficient (you don't have to keep repeating the same
conversation with perfect fidelity), because they can capture
details (not just vague impressions), because they can be reviewed,
critiqued, and corrected (unlike your trembling thoughts), because
they remain (unlike you, you job-hopper!), etc.
I don't deny the real peril of over-documentation, which is why an
agile project ought to insist that all documents are purposeful,
i.e. contribute to the knowledge construction. Neither do I deny the
value of conversation in a small team nor do I claim that all
knowledge can or should be captured in a document.
- I agree it's time for this thread to end. I'll close out my
contribution with some final comments here.
To Bret, who wanted an example of a requirement that needs an
enormous number of examples to completely express the code/tests to
be done, I refer to post #2896. (Another example from the aviation
business -- it's bizarre how often that domain has come up here.
Next time, you hold the giraffe.)
In arguing for the importance of specs, I have been feeling my way
around a concept I've called "Contract-Driven Development". To
Brian, who wanted an example of how CDD works, I refer to post
#2962. To be more concrete, at a detailed level (say, provoking a
new method), it would go something like this.
0. Consider what you intend the method to do.
1. Write the method signature, with Javadoc describing your
complete intentions. This is the contract. You want to know and
express your intentions as clearly and completely as you can, but
you expect that there might be some mistakes. You will cope with
this by iterating of this and succeeding steps as needed.
2. Confident the contract is right? If not, get some buddies to
review it and rework if necessary.
3. Based on the contract, write a test case.
4. Write the code that makes this test case pass.
5. Repeat #2-4 until you're satisfied the method code is complete
and correct. Notice that you could do #3 and #4 in any order or even
I feel that CDD can be just as agile as TDD. In fact, it's almost
exactly the same, except for the addition of #1-2. But what a
difference this makes! First, you end up with tests, code, and
contract. For others that come later, after all traces of your
current conversations have vanished, only the contract expresses
what you *intended* and therefore what they can or must do next.
Also, because the contract is real not tacit, you have a good chance
of finding and fixing defects sooner and cheaper. Also, a real (not
tacit) contract can be shared more reliably over time and space,
making it possible to create tests and code in parallel, with lower
communication cost and less backtracking.
I work exactly like this. Probably some of you do, too. I know it
works. But your experience may be different, so to progress we have
to look deeper, for principles plausible enough to try out on our
For example, I think CDD also makes sense at a higher level of
abstraction (say, when you're about to create a new class, or a new
set of collaborating classes, or a new UI screen, etc.) But here it
becomes less clear exactly which representations of the "contract"
can be both effective and agile. I don't have all the answers for
that, and I was hoping to learn more about it here, but so far I
haven't. (I know about FIT, but it suffers from the acknowledged
limitations of spec-by-example.)