Python's doc problems: sort

Discussion in 'Perl Misc' started by xahlee@gmail.com, Apr 30, 2008.

  1. Guest

    Of my Python and Perl tutorial at http://xahlee.org/perl-python/index.html

    the most popular page is

    “Sorting in Python and Perlâ€
    http://xahlee.org/perl-python/sort_list.html

    For example, in last week, that page is fetched 550 times.
    The second most popular page, trails quite a distance. Here's the top
    3 pages and their number of times fetched:

    550 http://xahlee.org/perl-python/sort_list.html
    341 http://xahlee.org/perl-python/system_calls.html
    222 http://xahlee.org/perl-python/index.html

    Note that the first 2 pages are far more popular than the entry page
    the table of contents.

    Apparently, and also verified by my web log, that people have
    difficulty in using sort, and they find my pages thru web search
    engines.

    ------------------

    In 2005, i wrote over ten essays detailing Python's documentation
    problems. One of them is titled:

    “Python Doc Problem Example: sort()â€
    http://xahlee.org/perl-python/python_doc_sort.html

    It's been 3 years, and python has gone from 2.4.x to 2.5.2.

    Looking at the current version of the doc, apparently, Python doc of
    that page hasn't improved a bit.

    I want to emphasize a point here, as i have done quite emphatically in
    the past. The Python documentation, is the world's worst technical
    writing. As far as technical writing goes, it is even worse than
    Perl's in my opinion.

    Although i disliked Perl very much, in part that it is lead by a cult
    figure that manipulates and deceives the populace, but there is at
    least one aspect of Perl community that is very positive, namely,
    embrace all walks of life. This aspect is taken by a Perl derivative
    the Pretty Home Page, and its success surpassed Perl, yet without
    Perl's cult string. Now, in my experience, the Python community, is
    filled with politics more so than Perl, and far more fucking assholes
    with high hats.

    Python priests: go **** yourselfs.

    (disclaimer: all statements about actual persons in this post are
    statements of opinion.)

    ----------------------

    Now, i find it pertinent to post my essay about the sort documentation
    problem again.

    The HTML version with colors and formatting is here:
    http://xahlee.org/perl-python/python_doc_sort.html

    Below is a abridged textual version.

    -------------------------------------

    Python Doc Problem Example: sort()

    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:

    «...»

    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 parameters are
    functions, often with the “lambda†construct. These are unusual and
    advanced constructs among imperative languages.

    • 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 notation the Python doc has adopted for indicating the syntax of
    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 itdoesn'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 oneof 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 laid 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.

    Addendum, 200510: Since Python 2.4 released in 2005-03, a new built-in
    function sorted() was added. There's no mention of it at the doc page
    of the sort() method.

    Addendum, 2005-10

    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.

    «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 employs the
    jargon “stable sort†then proceed to explain what it is, then in
    trying to illustrate the situation, it throws “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.â€


    Xah

    ∑ http://xahlee.org/

    ☄
     
    , Apr 30, 2008
    #1
    1. Advertising

  2. "" <> wrote:

    Is this self-promoting maniac still going at it?

    >Although i disliked Perl very much [...]


    Then why on earth do you bother polluting this NG?

    Back into the killfile you go

    jue
     
    Jürgen Exner, Apr 30, 2008
    #2
    1. Advertising

  3. On Apr 29, 11:13 pm, Jürgen Exner <> wrote:

    > "" <> wrote:
    >
    > Is this self-promoting maniac still going at it?
    >
    > >Although i disliked Perl very much [...]

    >
    > Then why on earth do you bother polluting this NG?
    >
    > Back into the killfile you go
    >
    > jue


    \|||/
    (o o)
    ,----ooO--(_)-------.
    | Please |
    | don't feed the |
    | TROLL's ! |
    '--------------Ooo--'
    |__|__|
    || ||
    ooO Ooo
     
    George Sakkis, Apr 30, 2008
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. John Wallace
    Replies:
    0
    Views:
    476
    John Wallace
    Jul 22, 2003
  2. Matt
    Replies:
    3
    Views:
    508
    Tor Iver Wilhelmsen
    Sep 17, 2004
  3. Praveen Chhangani

    Converting a org.jdom DOC to org.w3c DOC

    Praveen Chhangani, Aug 5, 2003, in forum: XML
    Replies:
    2
    Views:
    970
    Johannes Koch
    Aug 7, 2003
  4. Replies:
    11
    Views:
    433
    Martin Marcher
    Jun 2, 2008
  5. Navin
    Replies:
    1
    Views:
    699
    Ken Schaefer
    Sep 9, 2003
Loading...

Share This Page