[issue6765] math.log, log10 inconsistency

[steve21]

steve21 <steve872929-bv at yahoo.com.au> added the comment:

Mark,
"... that's what log10 is there for". That would be a good point if the
documentation said that. However, all the docs for log10 say is:

math.log10(x)
    Return the base-10 logarithm of x.

So we have a python function log10() which looks like it is redundant
since we can use log(a, 10) instead. But it actually functions
differently to log(a, 10), and the Python user would never know this
from looking at the documentation.

I think Tim Peters missed one important guideline in his "The Zen of
Python". The principle of least astonishment (or surprise) - when two
elements of an interface conflict, or are ambiguous, the behaviour
should be that which will least surprise the human user or programmer at
the time the conflict arises.

Its easy for the python developer to ignore this guideline. They know
the implementation, and are rarely surprised by inconsistent behaviour
since they have seen it before, or even created it without documenting it.

If Python functions are inconsistent then I think they should either be
made consistent, or if that's not possible they should be clearly
documented as being inconsistent.

The docs for log(x[, base]) could be improved to say:
"this function preserves the consistency of log(a,b) == log(a)/log(b)
but breaks consistency with log(a,10) == log10(a)"

The docs for log10(x) could be improved to say:
"this function gives the correct result for powers of 10,
but breaks consistency with log(a,10) == log10(a)"

----------

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