From: Richard Conroy <richard.conroy@...>
Date: 2010-06-23T06:58:48+09:00
Subject: Re: Help with Ruby return types and documentation

--0016e6dab08d5c9a730489a586d9
Content-Type: text/plain; charset=ISO-8859-1

On Tue, Jun 22, 2010 at 7:03 PM, Tasos Laskos <zapotek@segfault.gr> wrote:

> Hi Richard,
>
> Thanks a lot for your informative reply.
>
> You missed the one about coming from Java --not a big fun-- but I do
> appreciate its documentation.
>
>
Good API docs was always a quality of Java, even from the early days, but
Java needs it. Java libraries are very class heavy. The dynamic nature of
Ruby, coupled with powerful language features, means that you can do a
lot more with less classes and methods. Its a big leap to make though.


> My background is in C and PHP.
> PHP is dynamically typed too but the documentation is pretty clear about
> types and examples.
>

I don't have much experience with PHP, but from the opinions of those who
do,
I think a lot of PHP development is isolated within its standard library. In
Ruby
a lot of development uses a lot of 3rd party libraries/gems. I would say the
usage
of non-standard libraries in Ruby is above the median across all
programming
languages. Rails, which is about as conventional as Ruby development gets,
relies a lot on its extension mechanism. It would be pretty unusual to see
Rails projects that scorned all plugins. For non-Rails projects, nearly
anything goes,
and you can expect to see real world projects assembled almost entirely out
of
3rd party libraries that were not designed with each other in mind (Sinatra
+ Haml
+ DataMapper is actually a common enough combo).

This fact doesn't help the documentation situation much. And the APIs of the
best
stuff, do tend to be a bit of a moving target. There is also a bit of
competition in
significant problem domains (like web development, testing libraries, HTTP
clients
etc.). All of this means that documentation is not as verbose or complete as
you
would like it to be. Understanding an API is usually best accomplished by
running it
through IRB, studying source, or running the unit tests. All of which sounds
cavalier if you are used to working in languages/platforms where there are
significant
vendors.


> First day of Ruby today so I guess a working spider and half working
> analyzer isn't too bad of a progress.
>
>
Yeah. Not too shabby.


> I just have to get used to doing things the Ruby way, which I will
> eventually...unfortunately patience is not one of my qualities.
>

Well discipline is a more important virtue. There are a lot of very cool
libraries out there,
and its easy to get side tracked into them. Personally I have to be very
strict about the
amount of libraries I wish to learn at once (ideally just one) and ignore a
lot of cool things.

-- 
http://richardconroy.blogspot.com

--0016e6dab08d5c9a730489a586d9--