On Jan 19, 2006, at 10:43 AM, Mark Volkmann wrote:
> A particular thing I dislike is synonyms for methods in the built-in
> classes. Sure I can choose to use the method name that makes the most
> sense to me, but I still have to be aware of all the synonyms so I can
> read code that others wrote.

When I first starting reading this thread I was a bit puzzled as to
what features of Ruby are replicated in a variety of ways that might
cause confusion.

This message seems to indicate that the issue at hand is
library/api/class design and not necessarily Ruby the language.
I think it is an important distinction to make when discussing these
issues.

API/class/library design is *hard*.  Being an effective programmer
in any object oriented language is as much (if not more) about learning
the library as it is about learning the language semantics.

I think there is probably room for improvement in the Ruby documentation
to help people learn about the library.  An alphabetical list of methods
is helpful when you are looking for something in particular but when
you want to understand the structure of the API it isn't all that  
helpful.

I think Smalltalk had the idea of 'protocols' as named collections of
methods that could be used to navigate through large class libraries.
Eiffel has the 'flatten' tool to produce a complete API of a particular
class by incorporating all the methods defined in ancestors into a
version of the class documentation.   This would be helpful, for  
example,
with the File class which seems to be missing some important methods
until you realize that they are inherited from IO and documented there
instead of with File.

So I think better documentation tools/standards might make programmers
more effective in discovering, understanding, and using the class
libraries.


Gary Wright