On Jun 15, 2006, at 8:50 PM, Milan Zimmermann wrote:

>
>> The old joke "comments? why
>> do think it's called code?" sums up the antithesis of responsible
>> programming that seems to be the normal approach. Yes, reading the
>> code tells you what it *does* do (until you find a compiler bug for
>> example) but it tells you nothing about what it was intended to do,
>> what spec it was putatively meeting or what limits on its
>> functionality were known about.

So did tests, pre- / postconditions and counterexamples -- if they  
were known to focus on a given method.

If in doubt whether I should write a comment or a test, I'd go for  
the test.
Nice thing is, that the test not only helps other developers to  
understand the system, but also the computer to automatically...test it.
If I had enough time, I'd write both.

If there were a discussion to introduce a "documentation space" shown  
next to a given method to document it (as it is the case for classes  
right now) I'd strongly argue to use it for tests -- and not for  
comments.
You can find a suggestion for explicitly linking a test to a method  
here:
http://www.iam.unibe.ch/~scg/Archive/Papers/ 
Gael04cLinkingMethodsAndTests.pdf

Today I would either use method properties or blocks to denote the  
method under test (and not comments anymore...;-)
A better example than testing an accessor (as used in the screenshot  
of above paper - boooring) would help also to illustrate the power of  
a five-pane browser, where the fifth pane included tests.
Note that we could also easily extract the concrete types for the  
method under test - and - if we returned the result of a sampled  
method, also the instance variables of the class of the resulting  
object.

Cheers,

Markus