RE: Re: distinguishing between failures and errors

> From: J. B. Rainsberger [mailto:jbr@xxxxxxxxxxxxxxxxxxx]
>...
> > Isn't documentation the thing that should be used to tell the
> > writer of code that calls yours what your code is supposed to
> > do, or what the caller is supposed to do (or not do)?  (At
> > least for code meant to be re-used, such as that implementing
> > an API?)
> 
> Yes, it is. Please explain to me why unit tests are not 
> documentation. :)


Because tests aren't specifications. 

(How can a test show that the caller is responsible for not 
passing in a null pointer?

You can't test for any particular behavior from the callee
if the callee's behavior in the face of a null pointer is 
intentially left undefined (e.g., for flexibility in 
implementing an interface).)

(How can a test show that a caller is responsible for not
depending on certain current behavior of an implementation
that is not part of the interface contract?)


Because tests are code.  

(They have syntactic clutter that is necessary for use as tests 
but which is just clutter relative to the information useful to a 
client programmer.)


Because tests, being code, can't relate code to external concepts.  

(A specification can say that a function f returns the mathematical
sum of two given integers subject to the limitations of 32-bit
signed binary arithmetic.  How can a test say something like that?)


Tests are great, but don't forget the documentation.


It seems that some people who write tests waste one advantage of it:  

I agree that testing, especially writing tests even before you implement, 
is good because it forces you to think about what your code is supposed 
to do and how it's supposed to be used.  

Well, if you're already thinking about the contract, then that's a
good time to document the contract.  


Yes, I know this has to be modulated by what kind of code we're
talking about (e.g., intra-program calls versus trans-API calls) 
and by how stable the interface contract is.  I just wouldn't
want to have to read test cases instead of Javadoc to figure 
out how, say, Sun's Servlet API worked and was supposed to be 
used. 



Daniel