[Python-ideas] PEP 485: A Function for testing approximate equality

[Andrew Barnert]

Overall I like it, but I'm not sure the help on the tol parameter is clear enough for people who don't already know what they want--in other words, the very people this function should be helping.

In my experience, novices understand relative tolerance immediately if you put it in terms of "within X% of expected", but don't always understand it if you put it in terms of "within X * expected" or, worse, "relative to the magnitude of the expected value". Just using % in there somewhere makes people get the concept.

Unfortunately, since the API doesn't actually use a percentage--and shouldn't--I'm not sure how to get this across in a one-liner in the help. You can always add something like "(e.g., a relative tolerance of .005 means that the actual value must be within 0.5% of the expected value)", but that's way too verbose.

(Also, I should note that the people I've explained this to have mostly been people with a US 1960-1990-style basic math education; I can't be sure that people who learned in another country, or in the post-post-new-math era in the US, etc. will respond the same way, although I do have a bit of anecdotal evidence from helping a few people on forums like StackOverflow that seems to imply they do.)

Sent from a random iPhone

On Jan 22, 2015, at 16:40, Chris Barker <chris.barker at noaa.gov> wrote:

> is the relative tolerance -- it is the amount of error
> allowed, relative to the magnitude of the expected value.