PyWart: Itertools module needs attention
rantingrick at gmail.com
Tue Sep 13 22:08:34 EDT 2011
On Sep 13, 10:45 am, Ian Kelly <ian.g.ke... at gmail.com> wrote:
> Have you looked at the online itertools documentation at all?
Yes the online docs are much better. I really like the source code
showing the inner workings of the methods. However i always get upset
when i see poorly thought out doc-strings. My philosophy is that we
should use the built in help function first and only visit the
documentation if more instruction is needed.
I may need to create another PyWart on the topic of doc-strings and
how the author of these strings needs to forget everything he knows
and imagine he is a complete python neophyte. I remember my initial
frustrations learning about functions (in another life it seems) and
my inability to grasp the concept was due to poor examples. I believe
the author use the Fibonacci sequence as an example (Python docs use
this example also). What an idiot!
What does conditionals, linear assignment, loops, the print function,
in-place addition, logic, blah, blah, have to do with understanding a
function... NOTHING! The most basic and by far the best first example
for functions (in any language) is this...
def add(x, y):
return x + y
Followed by this...
return x - y
Simple and to the point. It simply reeks of "ah ha"! I dare anyone to
create a better introductory function example. Dear Tutorial Writer:
When writing tutorials please check your ego at the door. Thank you.
More information about the Python-list