friedo wrote: The Extreme Programming people say that the tests are the specification.

I see that a lot, but it always concerns me because I don't think it really holds true. Consider the following tests:

can_ok $object, 'copy_for_xmission';
ok my $clone = $object->copy_for_xmission, '... and copying should be 
+successful';
isa_ok $clone, 'Some::Class';
ok !defined $clone->ssn,                   '... but the SSN should not
+ be copied';
[download]

It's very common to see that in tests and it's perfectly appropriate. Now in reading the test output, we can see that the SSN is not copied on clone, but we don't know why. There are plenty of reasons why we might not copy the SSN over, but the tests tend to reflect what is happening, not why it's happening. As a result, tests document behavior, not business rules.

The problem with this is institutional knowledge. In many companies I've worked for, documentation is almost an afterthought. Some other programmer looking at this might can see the behavior, but when getting asked to extend or alter the behavior, they can easily make mistakes without an understanding of the underlying business reasons for the code's behavior. Programmers often claim that you should simply be able to read the code (or tests) to know what's going on but that ignores that the larger the system, the larger the number of assumptions which might creep into the code without explanation.