Python Doc Problem Example: sort() (reprise)

[Xah Lee]

Addendum, 200510

Here's further example of Python's extreme low quality of
documentation. In particular, what follows focuses on the bad writing
skill aspect, and comments on some language design and quality issues
of Python.

>From the Official Python documentation of the sort() method, at:
http://python.org/doc/2.4.2/lib/typesseq-mutable.html, Quote:

«The sort() method takes optional arguments for controlling the
comparisons.»

It should be “optional parameter” not “optional argument”.
Their difference is that “parameter” indicates the variable, while
“argument” indicates the actual value.

«... for controlling the comparisons.»

This is a bad writing caused by lack of understanding. No, it doesn't
“control the comparison”. The proper way to say it is that “the
comparison function specifies an order”.

«The sort() and reverse() methods modify the list in place for economy
of space when sorting or reversing a large list. To remind you that
they operate by side effect, they don't return the sorted or reversed
list. »

This is a example of tech-geeking drivel. The sort() and reverse()
methods are just the way they are. Their design and behavior are really
not for some economy or remind programers of something. The Python doc
is bulked with these irrelevant drivels. These littered inanities
dragged down the whole quality and effectiveness of the doc implicitly.

«Changed in version 2.4: Support for key and reverse was added.»

«In general, the key and reverse conversion processes are much faster
than specifying an equivalent cmp function. This is because cmp is
called multiple times for each list element while key and reverse touch
each element only once.»

When sorting something, one needs to specify a order. The easiest way
is to simply list all the elements as a sequence. That way, their order
is clearly laid out. However, this is in general not feasible and
impractical. Therefore, we devised a mathematically condensed way to
specify the order, by defining a function f(x,y) that can take any two
elements and tell us which one comes first. This, is the gist of
sorting a list in any programing language.

The ordering function, being a mathematically condensed way of
specifying the order, has some constraints. For example, the function
should not tell us x < y and y < x. (For a complete list of these
constraints, see http://xahlee.org/perl-python/sort_list.html )

With this ordering function, it is all sort needed to sort a list.
Anything more is interface complexity.

The optional parameters “key” and “reverse” in Python's sort
method is a interface complexity. What happened here is that a compiler
optimization problem is evaded by moving it into the language syntax
for programers to worry about. If the programer does not use the
“key” syntax when sorting a large matrix (provided that he knew in
advance of the list to be sorted or the ordering function), then he is
penalized by a severe inefficiency by a order of magnitude of execution
time.

This situation, of moving compiler problems to the syntax surface is
common in imperative languages.

«Changed in version 2.3: Support for None as an equivalent to omitting
cmp was added.»

This is a epitome of catering towards morons. “myList.sort()” is
perfect but Pythoners had to add “myList.sort(None)” interface
complexity just because idiots need it.

The motivation here is simple: a explicit “None” gives coding
monkeys a direct sensory input of the fact that “there is no
comparison function”. This is like the double negative in black
English “I ain't no gonna do it!”. Logically, “None” is not
even correct and leads to bad thinking. What really should be stated in
the doc, is that “the default ordering function to sort() is the
‘cmp’ function.”.

«Starting with Python 2.3, the sort() method is guaranteed to be
stable. A sort is stable if it guarantees not to change the relative
order of elements that compare equal -- this is helpful for sorting in
multiple passes (for example, sort by department, then by salary
grade).»

One is quite surprised to read this. For about a decade of a language's
existence, its sort functionality is not smart enough to preserve
order?? A sort that preserves original order isn't something difficult
to implement. What we have here is sloppiness and poor quality common
in OpenSource projects.

Also note the extreme low quality of the writing. It employes the
jargon “stable sort” then proceed to explain what it is, and the
latch on of “multiple passes” and the mysterious “by department,
by salary”.

Here's a suggested rewrite: “Since Python 2.3, the result of sort()
no longer rearrange elements where the comparison function returns
0.”
-----------
This post is archived at:
http://xahlee.org/perl-python/python_doc_sort.html

 Xah
 xah at xahlee.org
∑ http://xahlee.org/