# [Python-Dev] trace.py and the obscurity of Tools/scripts/ (was: Unittest list)

Tim Peters tim.one@comcast.net
Thu, 11 Apr 2002 14:59:35 -0400

```[Zooko]
> ...
> It would require better docs regarding the programmatic usage.

I believe it needs much better docs period.  I've tried to steer people
toward it, but they just can't figure out how to use it.

> Anything else that would be required for trace to make this transition?

It would help if the bugs were fixed, or identified as common gotchas and
explained in the hypothesized better docs <wink>.  For example,

def f(n):
sum = 0
for i in range(n):
sum
for j in range(n):
sum += 1
return sum

print f(10)

produces a .cover file containing

2: def f(n):
2:     sum = 0
12:     for i in range(n):
10:         sum
120:         for j in range(n):
100:             sum += 1
1:     return sum
.
1: print f(10)

Half the counts reported are "a surprise" to the uninitiated in one way or
another; most people seem to expect

1: def f(n):
1:     sum = 0
1:     for i in range(n):
10:         sum
10:         for j in range(n):
100:             sum += 1
1:     return sum
.
1: print f(10)

while a smaller but still significant number seem to expect

1: def f(n):
1:     sum = 0
11:     for i in range(n):
10:         sum
110:         for j in range(n):
100:             sum += 1
1:     return sum
.
1: print f(10)

I realize "intuitive" counts are hard to achieve, but if it's in the
standard library I'm likely to become the one who has to try to explain
"non-intuitive" counts away year after year after year.  So, to save myself
a couple years of possibly otherwise happy life <wink>, I'm -1 unless the
docs do a great job of cutting off questions before they get asked.

```