[issue3318] Documentation: timeit: "lower bound" should read "upper bound"

[unutbu]

unutbu <driabslg at yahoo.com> added the comment:

Dear Georg,
     Would you please reconsider this issue (http://bugs.python.org/issue3318) for a moment?

The term "lower bound" as it is used in the timeit documentation is either misleading or mathematically incorrect. A lower bound is a number which is less than or equal to every member of a set. What set is the timeit documentation referring to? Here are two possibilities:

A = the set of times recorded from three runs
B = the set of all possible times a particular machine could return

The term "lower bound" is technically correct if the documentation means "lower bound of set A", but I think it would be misleading to use the term "lower bound" in this way, since the documentation would then be asserting: "the minimum time of three runs is the lower bound of three runs". It's not very exciting, and moreover, it's obvious. 

The term "lower bound" is simply incorrect if the documentation meant "lower bound of set B". I explained the reason why in my first post.

I appreciate your point when you said, "An ideal machine is not useful in practice". 
However, the documentation opens up this can of worms by its own use of the term lower bound. If ideal machines is not what it wants to discuss, then maybe the documentation needs to be changed in some other way to avoid the mathematically charged term, "lower bound".

I think you would agree that good documentation needs to use language accurately. The documentation as it stands is either fallacious (if it is talking about set B), trivial (if it is talking about set A), or possibly correct if it is talking about some set C which I have not imagined.

If it is the latter case, please update the documentation to make clear what set C is.

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3318>
_______________________________________