[Haskell-cafe] Poor libraries documentation
Anton van Straaten
anton at appsolutions.com
Thu Jan 31 09:46:23 EST 2008
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
> 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
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.
More information about the Haskell-Cafe