Use the Source Luke

[Raymond Hettinger]

[Jack Diedrich]
> I think you overestimate how common it used to be to carry around the
> sourcecode for the software you use compared to now;  In the past it
> wasn't even always possible - if the Sun cc compiler core dumps you
> have no recourse to code.

You're right of course.  For the Python world though, there does seem
to have been a change.  A decade ago in this newsgroup, there were
frequent references to standard library source.  I don't see that
much anymore.


> Promoting the idea of doing it is good
> because it /is/ a novel idea to many people.  Promoting the idea of
> making it extremely easy via documentation links is good because it is
> new as well.

Judging from the comments so far, it looks like everyone here agrees.

> Modern tools are making this easier than it used to be so your call
> for making it easier still is well timed.  Github/bitbucket/launchpad
> have combined the source with documentation;

Do they typically feature multiple links from documentation specifics
to corresponding code specifics?

Part of my thesis is that it is not enough to make docs and source
available, they need to be linked in a way that helps people
answer specific problems without having to invest a week in learning
the gestalt of a foreign code base.


> Worst case the docstrings suck and I just read the code.

That's a good habit to have.  I find that my willingness to do it
varies across projects -- I'm happy to look at the Mercurial source
but could never being myself to look at the innards of Git or CouchDB.


> * Anecdote.  I was in a room with Tim Peters and has some questions
> about the interface to code he wrote so I thought "Hey, I'll just ask
> Tim!"  I asked him and he replied "I'm not sure what you're asking -
> do you want me to read the code aloud to you?"  So I just went and
> read it.

Thanks for the anecdote.  I love that story :-)
Uncle Timmy's style is both clever and pointed.


Raymond