On 22/08/06, Just Another Victim of the Ambient Morality
<ihatespam / rogers.com> 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...
>
>
>
>
>

In my experience the way to handle this is to have parameters and
variables with logical, consistent names. If I'm debugging a function
'foo(i)' it's almost impossible to know what  is. If the function
instead was defined as 'foo(categoryName)' it's a lot easier to deduct
that it's a (string or an object that should be able to ducktyped to a
string).

Farrel