[Haskell-cafe] Poor libraries documentation

[Anton van Straaten]

Derek Elkins wrote:
> On Wed, 2008-01-30 at 22:19 -0500, Anton van Straaten wrote:
...
>> We discover a function called, say, "cos", probably by guessing it's 
>> name, run a very small number of simple tests on it, see the answers we 
>> expect, and decide that it's the function we want.  Does anyone want to 
>> defend that on safety/correctness grounds?  But some of us do it anyway.
> 
> It depends on the extent.  Deciding between degrees and radians, this
> works perfectly if you have any idea what you are doing.  

But deciding between degrees and radians is only one of the assumptions 
you'd be making, if you don't check the docs.

In general, this argument sounds similar to the sort of arguments that 
are given in defense of all sorts of unsafe activities -- dynamic 
typechecking comes to mind, or unhygienic macros: "works perfectly if 
you have any idea what you are doing".  While it may usually be true, 
it's often not considered a valid argument if safety and correctness are 
important.

> Arguably, this
> -is- more defensible on a safety/correctness grounds than reading the
> documentation.  Documentation can be out of date or wrong or right but
> the implementation is wrong.  So it comes down to a matter of
> trust/convincing.

Reading the documentation alone isn't enough from a correctness 
perspective - you also need to test.  As Reagan liked to put it, trust 
but verify.  But similarly, testing alone isn't enough.  There could be 
caveats in the documentation that could affect your program, that you 
don't detect in your tests.

And yes, you also might come across a discrepancy between documentation 
and the actual behavior, which is something you'd want to investigate if 
correctness is important.  Actual instances of discrepancies between 
documentation and code are a bug, but the fact that the two can get out 
of sync is a feature: it acts as a cross-check, and the purpose of 
cross-checks is that sometimes they fail.

If you're concerned about safety and correctness, then ignoring 
available information about functions you use, and assuming that 
behavior is as you expect, still seems hard to defend, to me.