From: Just Another Victim of the Ambient Morality <ihatespam@...>
Date: 2006-08-22T21:30:19+09:00
Subject: Static typing ain't so bad, after all...

    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...