Comments on Convince me to use Python: Ruby's Achilles heel...

Glenn said "That's probably how about 90% of my de...

2008-05-02T11:54:00.000-07:00

Glenn said "That's probably how about 90% of my dealings with new modules goes -- import x, help( x ), use x."

Even better, give ipython a try. This gives you direct access to the python docstrings, context sensitive tab completion, and much much more.

Here is the ipython equivalent of your example (N.B. [tab] means hit the tab key):

import x[tab]
# (lists and cycles through all the modules on the path that start with x)

x?
# (prints information about x, including the file it is defined in and its docstring)

x??
# (prints even more information about x, including the syntax highlighted source code)

x.[tab]
# (lists and cycles through the methods & attributes on x)

x.foo?

# (prints info on the foo method or attribute of x)

and so on. You can also use the same help() system as in the regular python interpreter.

I hardly ever need to refer to the Python docs, excellent though they are, since it is usually quicker and easier to ask ipython.

FREE Python docs & books. Search FSF's free books ...

2008-05-01T12:37:00.000-07:00

FREE Python docs & books. Search FSF's free books list for Python & Zope, then search it for Ruby & Rails. No comparison, pals.

Python is missing some documentation, but by-and-l...

2008-05-01T00:03:00.000-07:00

Python is missing some documentation, but by-and-large I would say most things are well documented.

Consider this session ( feel free to follow along ina a python session of your own ):
$ python
...
>>> import md5
>>> help( md5 )
>>> hasher = md5.new()
>>> hasher.update( 'hello' )
>>> hasher.hexdigest()
'5d41402abc4b2a76b9719d911017c592'
>>>

That's probably how about 90% of my dealings with new modules goes -- import x, help( x ), use x.

Mr Neighbourly said "Even further, there are a num...

2008-04-26T02:07:00.000-07:00

Mr Neighbourly said "Even further, there are a number of things in Python that aren't documented, but the documentation tools skip them if there isn't any documentation. :)".

Can you give some examples of the "number of things" in Python that are not documented? That sounds like FUD to me.

That's why there is much interest and lots of acti...

2008-04-25T05:42:00.000-07:00

That's why there is much interest and lots of activities in various efforts like Ruby Specification Wiki and RubySpec conformance test suites, etc. Also, new book "The Ruby Programming Language", co-authored by Matz, serves as a good description/specification of Ruby Language.

Are you all really wasting time in this pointless ...

2008-04-25T05:20:00.000-07:00

Are you all really wasting time in this pointless discussion? C'mon, grow up. Brian said it all. 'Nuff said.

For a language that is so "easy to read" who needs...

2008-04-24T17:51:00.000-07:00

For a language that is so "easy to read" who needs documentation?

@mr. neighborly: I challenge you to point out one....

2008-04-24T17:23:00.000-07:00

@mr. neighborly:

I challenge you to point out one...that's right...just one...piece of Python's core or standard libraries that isn't documented. Seriously...

A few months ago, I printed out Python's MD5 docs ...

2008-04-24T13:46:00.000-07:00

A few months ago, I printed out Python's MD5 docs and stuck them in the Ruby section of my 3-ring binder. Oy.

My "favorite" piece of undocumented Ruby is Config::CONFIG (rbconfig).

While I appreciate your mentioning this, and there...

2008-04-23T18:11:00.000-07:00

While I appreciate your mentioning this, and there are a lot of areas where Ruby is poorly documented, I think picking out one of the few places where documentation is non-existent is a little unfair. Even further, there are a number of things in Python that aren't documented, but the documentation tools skip them if there isn't any documentation. :)

We're working on fixing this and other documentation faults.

Ruby and Python share many similarities, and they ...

2008-04-23T15:37:00.000-07:00

Ruby and Python share many similarities, and they don't stop just at the language. Both are open source, and both arguably fall into the camp of having a BDFL (a Benevolent Dictator For Life, for the uninitiated). Some would argue that Linux also falls into this category.

While much of the inspiration, direction and sweat equity has been (originally) sourced from a single person [Matz, Guido, Linus], as open source projects, they and their accompanying documentation belong to their respective communities.

The qualitative differences you're pointing out in comparing the documentation of a python class to a ruby class are certainly valid. The distinction I would make, however, is that this is not a problem with the Ruby language, but falls on the Ruby community of which we all consider ourselves a part.

To that end, the solution is not only within reach, but it's our responsibility to carry out. Instead of pointing blame at Ruby, let's look to ourselves and ask not what has Ruby done for me, but what can I do for Ruby? (apologies to JFK ;)

If you search many of the popular Ruby newsgroups you'll find this topic has received much attention lately. I do hope that parlays into an organized effort, to which I'm happy to participate, in providing better documentation, in the public domain(!) that serves us, and our favorite language, all at once.

The ruby version doesn't even list real methods. M...

2008-04-23T15:13:00.000-07:00

The ruby version doesn't even list real methods. MD5 is a class object with several useful methods, none of them documented:

irb(main):001:0> require 'digest/md5'
=> true
irb(main):002:0> Digest::MD5.public_methods(false)
=> ["digest", "file", "hexdigest", "allocate", "superclass", "new"]
irb(main):003:0> quit

$ ri MD5.digest
Nothing known about MD5.digest

$ ri MD5.hexdigest
Nothing known about MD5.hexdigest

And so on...