While we're talking about annoyances

[Steven D'Aprano]

Am I the only one who finds that I'm writing more documentation than code?

I recently needed to write a function to generate a rank table from a
list. That is, a list of ranks, where the rank of an item is the position
it would be in if the list were sorted:

alist = list('defabc')
ranks = [3, 4, 5, 0, 1, 2]

To do that, I needed to generate an index table first. In the book
"Numerical Recipes in Pascal" by William Press et al there is a procedure
to generate an index table (46 lines of code) and one for a rank table
(five lines). 

In Python, my index function is four lines of code and my rank function is
five lines. I then wrote three more functions for verifying that my index
and rank tables were calculated correctly (17 more lines) and four more
lines to call doctest, giving a total of 30 lines of code.

I also have 93 lines of documentation, including doctests, or three
lines of documentation per line of code.

For those interested, here is how to generate an index table and rank
table in Python:


def index(sequence):
    decorated = zip(sequence, xrange(len(sequence)))
    decorated.sort()
    return [idx for (value, idx) in decorated]

def rank(sequence):
    table = [None] * len(sequence)
    for j, idx in enumerate(index(sequence)):
        table[idx] = j
    return table


You can write your own damn documentation. *wink*



-- 
Steven.