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?
>     Thank you...

Zen.

T.