Python Doc Problem Example: sort() Xah Lee, 200503 Exhibit: Incompletion & Imprecision
Python doc “3.6.4 Mutable Sequence Types” at http://python.org/doc/2.4/lib/typesseq-mutable.html in which contains the documentation of the “sort” method of a list. Quote: « Operation Result Notes s.sort([cmp[, key[, reverse]]]) sort the items of s in place (7), (8), (9), (10) (7) 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. (8) The sort() method takes optional arguments for controlling the comparisons. cmp specifies a custom comparison function of two arguments (list items) which should return a negative, zero or positive number depending on whether the first argument is considered smaller than, equal to, or larger than the second argument: "cmp=lambda x,y: cmp(x.lower(), y.lower())" key specifies a function of one argument that is used to extract a comparison key from each list element: "cmp=str.lower" reverse is a boolean value. If set to True, then the list elements are sorted as if each comparison were reversed. 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. Changed in version 2.3: Support for None as an equivalent to omitting cmp was added. Changed in version 2.4: Support for key and reverse was added. (9) 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). (10) While a list is being sorted, the effect of attempting to mutate, or even inspect, the list is undefined. The C implementation of Python 2.3 and newer makes the list appear empty for the duration, and raises ValueError if it can detect that the list has been mutated during a sort. » As a piece of documentation, this is a lousy one. The question Python doc writers need to ask when evaluating this piece of doc are these: • can a experienced programer who is expert at several languages but new to Python, and also have read the official Python tutorial, can he, read this doc, and know exactly how to use sort with all the options? • can this piece of documentation be rewritten fairly easily, so that the answer to the previous question is a resounding yes? To me, the answers to the above questions are No and Yes. Here are some issues with the doc: • In the paragraph about the “key” parameter, the illustration given is: “cmp=str.lower”. It should be be “key=str.lower” • This doc lacks examples. One or two examples will help a lot, especially to less experienced programers. (which comprises the majority of readers) In particular, it should give a full example of using the comparison function and one with the “key” parameter. Examples are particularly needed here because these parameteres are functions, often with the “lambda” construct. These are unusual and advanced constructs among imperative programers. • This doc fails to mention what happens when the predicate and the shortcut version conflicts. e.g. “myList.sort(cmp=lambda x,y: cmp(x[0], y[0]), key=lambda x: str(x[1]) )” • The syntax notation Python doc have adopted for indicating optional parameters, does not give a clear view just exactly what combination of optional parameters can be omitted. The notation: “s.sort([cmp[, key[, reverse]]])” gives the impression that only trailing arguments can be omitted, which is not true. • The doc gives no indication of how to omit a optional arg. Should it be “nul”, “Null”, 0, or left empty? Since it doesn't give any examples, doc reader who isn't Python experts is left to guess at how true/false values are presented in Python. • On the whole, the way this doc is written does not give a clear picture of the roles of the supplied options, nor how to use them. Suggested Quick Remedy: add a example of using the cmp function. And a example using the “key” function. Add a example of Using one of them and with reverse. (the examples need not to come with much explanations. One sentence annotation is better than none.) Other than that, the way the doc is layed out with a terse table and run-on footnotes (employed in several places in Python doc) is not inductive. For a better improvement, there needs to be a overhaul of the organization and the attitude of the entire doc. The organization needs to be programing based, as opposed to implementation or computer science based. (in this regard, one can learn from the Perl folks). As to attitude, the writing needs to be Python-as-is, as opposed to computer science framework, as indicated in the early parts of this critique series. ---------------- This post is archived at: http://xahlee.org/perl-python/python_doc_sort.html Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list