Hi --

On Tue, 22 Aug 2006, Just Another Victim of the Ambient Morality wrote:

>    I was debugging someone else's code the other day (it was htmltools,
> actually) and I was in the middle of some function trying to figure out
> what it does.  That's when I noticed that I had no clue what the passed in
> parameter was.  I mean, I can see how it was used but it really didn't
> reveal what it was.  In fact, it could have been anything.  I could have
> tried to do a search to see when this method was called and try to
> investigate what was passed in at each instance but that would not
> necessarily be revealing since the object may not have been created in
> those methods and, instead, passed into them.
>    The problem is that dynamic typing, while very powerful, also hid the
> intent of the method.  Obviously, any object that satisfied whatever the
> method was trying to do will suffice as a parameter, and that would be the
> point of duck typing, there was obviously some concrete example of some
> type the method was expecting.  It would really have helped to let me know
> what that was...
>    Now, the answer to this is simply better documentation.  Write a damn
> comment that says what the method is expecting and, hell, while you're at
> it, you could mention what the method does, too.  However and
> unfortunately, I've been a professional programmer way too long to expect
> code to come with good documentation.  Out here, in the real world, you're
> lucky if the code works...
>    Has anyone noticed this?  How do you deal with this issue?

I think a good first step is to read "Programming Ruby" by Dave Thomas
et al., especially the part where he explains in detail that type and
class are not the same thing in Ruby.

Also, please -- PLEASE -- read the hundreds, or perhaps thousands, of
posts about this in the ruby-talk archives.  I'm not optimistic about
breaking the cycle; it seems we're doomed to have this thread repeated
three or four times a year.  But, I don't know, maybe one of these
years we can stop.

Don't take my curmudgeonliness personally.  It's just that there's
really not much else left to say on the topic.


David

-- 
http://www.rubypowerandlight.com => Ruby/Rails training & consultancy
   ----> SEE SPECIAL DEAL FOR RUBY/RAILS USERS GROUPS! <-----
http://dablog.rubypal.com        => D[avid ]A[. ]B[lack's][ Web]log
http://www.manning.com/black     => book, Ruby for Rails
http://www.rubycentral.org       => Ruby Central, Inc.