[Haskell-cafe] Poor libraries documentation

[Derek Elkins]

On Thu, 2008-01-31 at 09:46 -0500, Anton van Straaten wrote:
> 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.

This was the scenario that was presented.  Again, it depends on the
extent; what do you already know (or are assuming) and what is relevant
to you.

> 
> 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.

My situation was for the case between just reading the documentation and
just "playing" with it.  Neither situation corresponds to what you would
do in safety critical code, but that wasn't the original situation which
-was- deciding between degrees and radians under the assumption that we
already know the cos .  As you say, if you care, you will need to test.
Depending on how much assurance you want, you might use various formal
and informal methods to better convince yourself (and the customer), but
even in those cases you will do testing.