bizarro world (was Re: Python Doc Problem Example: sort() (reprise))

Bryan belred at
Wed Oct 12 07:56:18 CEST 2005

Xah Lee wrote:
> 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:
>, 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 )
> 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:
>  Xah
>  xah at

omg!!! wow!!! after reading this i feel like i just stepped in to some bizarro 
world.  this entire posting is like something you would read in the onion. 
unfortunately this posting has just enough real words mixed with BS that a 
newbie might actually fall for this stuff.  i think mr. xah has published enough 
python satire by now that we could probably make a nice bathroom reading book 
"python untechgeeked".  sorry folks, i'm still laughing... i just don't get how 
someone can go on and on and on, day after day, month after month writing this 
stuff that is so completely off base that you wonder if he's looking at the same 
python as we are.  mr. xah, why do you spend so much time agonizing over a 
language you obviously don't like.  why is python so important to you that you 
are willing to waste so much of your life on this?  there is obviously something 
else i'm not seeing here.  is there a pschologist in the house?  can someone 
explain xah to me?  is he clinically depressed? suicidal? does he have signs of 
a serial murderer?  does he need a girl friend and a social life?  or maybe just 
take a yoga class? could these ramblings of his simply be on days that he 
doesn't take his medication?  i'm starting to think he is not simply just a 
troll.  i think there might be something seriously wrong with him and this is 
just his way of asking for help.  maybe i'm wrong, there was just something is 
his last writings that made think he's hurting inside.

More information about the Python-list mailing list