Use the Source Luke

[Steven D'Aprano]

On Mon, 31 Jan 2011 12:35:12 -0800, Raymond Hettinger wrote:

> However, even the parts of the standard library written in pure Python
> don't seem to be getting read anymore, so I'm still inclined to
> attribute the issue to 1) inconvenient placement of source code, 2) a
> largish code base, and 3) possibly a cultural shift.

I'd be inclined to say that #3 is by far the most important. When I 
started programming, the internet wasn't even a distant object on radar. 
(That is to say, it existed, but hardly anyone outside of a few gurus at 
universities had even heard of it.) If you wanted to learn a language, 
you bought a book and read it, if one existed and you could afford it, 
and you read the sample code that came with the software. Often the book 
you bought told you to read the sample code. You couldn't email a mailing 
list to ask for help, or post to a forum, or google the answer. If you 
were lucky, you could go to a Users Group once a month or so. And so "old 
timers" learned to read the source, because that's almost all there was.

Today's newbies take the internet, web forums, mailing lists, usenet and 
google for granted. This is a *big* cultural shift.

As for #1, in truth I don't believe it is actually a problem. Okay, it 
might be a bit inconvenient to find the Python source code the first few 
times you go looking (I can never remember whether to look in
/usr/lib/python or /usr/local/lib/python), but once you've found it, it 
isn't difficult to create a shortcut for it. And as for #2, yes, there 
may be a lot of code in the standard library, but it's all cut up into 
small, easily swallowed chunks called "modules" :)

In my experience, the biggest obstacles for people to read the Python 
code in the standard library are:

(1) thinking to do so in the first place; and

(2) the chicken-and-egg problem that as a newbie they often don't 
understand what they're reading.


Your idea of including links to source in the documentation will 
hopefully help with the first.


-- 
Steven